Setup

Add with JitPack

Release

Step 1

Add jitpack.io to your root build.gradle at the end of repositories:

allprojects {
  repositories {
    ...
    maven { url 'https://jitpack.io' }
  }
}

Step 2

Add Internet permission to your AndroidManifest.xml:

<manifest>
    ...
    <uses-permission android:name="android.permission.INTERNET" />
</manifest>

Step 3

Add Pelcro SDK dependency:
Our latest Android SDK package version is 1.1.7

dependencies {
  implementation 'org.bitbucket.michael-pelcro:android-sdk:1.1.1'
}

Usage

Initialize

Initialize Pelcro SDK with your parameters:
In Java:

Pelcro.INSTANCE.setSiteID("Your site ID");
Pelcro.INSTANCE.setAccountID("Your account ID");
Pelcro.INSTANCE.setStripeSandbox(false); // false - for Production, true - for Development
Pelcro.INSTANCE.setPelcroStaging(false); // false - for Production, true - for Development

In Koltin:

Pelcro.siteID = "Your site ID"
Pelcro.accountID = "Your account ID"
Pelcro.isStripeSandbox = false // false - for Production, true - for Development
Pelcro.isPelcroStaging = false // false - for Production, true - for Development

Create Site manager

In Java:

PelcroSiteManager siteManager = new PelcroSiteManager(this);

In Koltin:

val siteManager = PelcroSiteManager(this)

Get site info

In Java:

siteManager.getSite(new ResultHandler() {
    @Override
    public void onResult(PelcroResult result) {
        Log.i("PelcroResult: ", result.toString());
    }
});

In Koltin:

siteManager.getSite(object : ResultHandler {
    override fun onResult(result: PelcroResult) {
        Log.i("PelcroResult: ", result.toString())
    }
})

Note: once you've called siteManager.getSite(...), you can get result data using method siteManager.read(). This data will be kept in the memory during your Application's session.

Create User manager

In Java:

PelcroUserManager userManager = new PelcroUserManager(this);

In Koltin:

val userManager = PelcroUserManager(this)

Register

In Java:

userManager.registerWith("Your email", "Your password", new ResultHandler() {
    @Override
    public void onResult(PelcroResult result) {
        Log.i("PelcroResult: ", result.toString());
    }
});

In Koltin:

userManager.registerWith("Your email", "Your password", object: ResultHandler {
    override fun onResult(result: PelcroResult) {
        Log.i("PelcroResult: ", result.toString())
    }
})

Login

In Java:

userManager.loginWith("Your email", "Your password", new ResultHandler() {
    @Override
    public void onResult(PelcroResult result) {
        Log.i("PelcroResult: ", result.toString());
    }
});

In Koltin:

userManager.loginWith("Your email", "Your password", object: ResultHandler {
    override fun onResult(result: PelcroResult) {
        Log.i("PelcroResult: ", result.toString())
    }
})

Refresh

In Java:

userManager.refreshWith(new ResultHandler() {
    @Override
    public void onResult(PelcroResult result) {
        Log.i("PelcroResult: ", result.toString());
    }
});

In Koltin:

userManager.refreshWith(object : ResultHandler {
    override fun onResult(result: PelcroResult) {
        Log.i("PelcroResult: ", result.toString())
    }
})

Logout

In Java:

userManager.logout();

// Then you can check auth token, it should be empty
String authToken = userManager.getAuthToken();

In Koltin:

userManager.logout()

// Then you can check auth token, it should be empty
val authToken = userManager.authToken

Note: once you've called one of methods of userManager (except for logout() method), you can get result data using method userManager.read(). This data will be kept in the memory during your Application's session.

Create Subscription manager

In Java:

PelcroSubscriptionManager subscriptionManager = new PelcroSubscriptionManager(this);

In Koltin:

val subscriptionManager = PelcroSubscriptionManager(this)

Create a subscription

Step 1

Implement PaymentTokenCallback in your Activity and override onSuccess(stripeToken: String), onError(message: String?) and onCancelled() methods. These methods allow to get callbacks from PaymentMethodDialogFragment to your Activity. If you enter valid card information on PaymentMethodDialogFragment you should get Stripe Token to the method onSuccess(stripeToken: String), in case you are cancelled or something went wrong you should get callbacks to onCancelled() or onError(message: String?) methods.

Step 2

Create PaymentMethodDialogFragment and show this dialog:

In Java:

PaymentMethodDialogFragment.newInstance().show(getSupportFragmentManager(), "tag");

In Koltin:

PaymentMethodDialogFragment.newInstance().show(supportFragmentManager, "tag")

Step 3

Create a subscription

In Java:

subscriptionManager.createWithStripe(-1L /*Plan ID*/, "Coupon code", "Stripe token", new ResultHandler() {
    @Override
    public void onResult(PelcroResult result) {
        Log.i("PelcroResult: ", result.toString());
    }
});

In Koltin:

subscriptionManager.createWithStripe(-1L /*Plan ID*/, "Coupon code", "Stripe token", object : ResultHandler {
    override fun onResult(result: PelcroResult) {
        Log.i("PelcroResult: ", result.toString())
    }
})

Cancel a subscription

In Java:

subscriptionManager.cancelWith(-1L /*Subscription ID*/, new ResultHandler() {
    @Override
    public void onResult(PelcroResult result) {
        Log.i("PelcroResult: ", result.toString());
    }
});

In Koltin:

subscriptionManager.cancelWith(-1L /*Subscription ID*/, object : ResultHandler {
    override fun onResult(result: PelcroResult) {
        Log.i("PelcroResult: ", result.toString())
    }
})

Reactivate a subscription

In Java:

subscriptionManager.reactivateWith(-1L /*Subscription ID*/, new ResultHandler() {
    @Override
    public void onResult(PelcroResult result) {
        Log.i("PelcroResult: ", result.toString());
    }
});

In Koltin:

subscriptionManager.reactivateWith(-1L /*Subscription ID*/, object : ResultHandler {
    override fun onResult(result: PelcroResult) {
        Log.i("PelcroResult: ", result.toString())
    }
})

Check if user is subscribed to site

In Java:

Boolean isSubscribedToSite = subscriptionManager.isSubscribedToSite();

In Koltin:

val isSubscribedToSite = subscriptionManager.isSubscribedToSite()

Note: Before using isSubscribedToSite() method you need to call one of userManager methods: registerWith(...), loginWith(...) or refreshWith(...). In other words userManager.read() shouldn't return null. If userManager.read() returns null or Pelcro.siteID didn't set then method isSubscribedToSite() also will return null, otherwise it will return expected result - true or false.

Testing

We created custom shadows in order to test objects from the Android ecosystem. Therefore, if you want to test something related to these objects, please check these shadows. So far we added shadows for:
android.os.AsyncTask
java.io.InputStream
javax.net.ssl.HttpsURLConnection
org.json.JSONObject

Note: We recommend using a real device for testing during the development stage. That's because data, which is cached in the Pelcro SDK, might not be read from a virtual device's storage.

License

The Pelcro Android SDK is open source and available under the MIT license. See the LICENSE file for more info.

FAQs

Are there social logins in the Android SDK?
Unfortunately, social logins are not directly supported in the Android SDK, but this is available through our Open API endpoint. More information can be found here.

Can a user create an account on the website and use its login in the app? And vice-versa?

Yes, a user can create an account on the website and use its login in the app, and vice-versa. The authentication system is synchronized across the platform, allowing for seamless login experiences between the website and mobile apps.

After an In-App Purchase, How Are the Subscriptions Managed?

To manage subscriptions on Pelcro after an in-app purchase, you should configure subscriptions in App Store Connect with the same parameters (price, duration, etc.) as you have for the plan in Pelcro and use our PelcroSubscriptionManager functionalities to manage the subscription.

Do We See the Subscription in the Pelcro Dashboard?

Yes, if you manage to create a subscription in the App Store with the same plan parameters as used in Pelcro's subscription manager, you will be able to view it in the Pelcro dashboard.

Can We Cancel an in-app subscription in Pelcro Dashboard?

You can cancel subscriptions through the Pelcro dashboard. However, it is essential to note that this action only affects the Pelcro side. The cancellation or reactivation on the App Store must be handled separately.

I canceled my Pelcro subscription through the app, but is it also canceled in the App Store?
No, canceling a subscription through the Pelcro app (using the SDK) only affects your Pelcro account. You'll need to take separate steps to cancel the subscription in the App Store itself. This ensures you don't get charged again by Apple.

Can I see invoices for in-app purchases on the Pelcro dashboard?
Yes, but only if you meet two conditions:

The in-app purchase plan matches a Pelcro subscription plan.
You create the subscription in Pelcro's Core API.

Do we support Coupon Codes with in-app purchases?

Yes, both our Open API and Core API can be leveraged to create subscriptions with a valid coupon.

Open API: The end-user needs to be authenticated first, as this endpoint is protected and requires a valid authentication token.
Core API: You will need to know the Customer ID to create the subscription.

Is it best practice to execute Core API requests through a mobile app for validating user existence?
It's generally recommended to use the Open API instead if customers can directly obtain user data on sign-ups.

Can I tell if a subscription came from the app, website, or in-app purchase?
Yes, but you need to set up a process using Pelcro's Core API. Here's how:

Listen to thecharge.succeeded event.
Check the origin field to see if the payment came from an Apple in-app purchase (origin will be set to 3).
Update the subscription's metadata with the origin information (website, app, etc.).

Why shouldn't I use the Core API directly in my mobile app?

Exposing the Core API key in your app creates a security risk for fraud activities.

How long is a login token valid for in the app?

Does the token refresh automatically if I use the app?

No, the token itself doesn't refresh automatically by you using the app. However, there's a separate endpoint called "Refresh customer" that can be used to get a new token.

How can I test login flows with valid and invalid tokens?

Valid Token: Use a real token obtained after login.
Invalid Token: You can manipulate a valid token (e.g., change some data) to simulate an invalid one.