Integrating Adapty SDK

There are two ways to integrate Adapty SDK: Observer mode and Full mode. We'll take a quick look at them, and then proceed to detailed integration instructions for iOS and Android.

Observer mode gives you full analytics capabilities:

  • Integrations including attribution systems;

  • Advanced Dashboard;

  • Profiles CRM.

Integrating it usually takes under an hour, you'll only need to implement a couple of SDK methods. You can use Observer mode along with existing purchases infrastructure.

Full mode adds multiple features on top of Observer:

  1. Complete purchases infrastructure: managing access to the app including lifetime, handling renewals, billing retries, subscription offers, grace periods, etc.;

  2. A/B testing;

  3. Promo Campaigns.

Integration takes several hours, and in most cases, you should use Full mode as a complete solution for your app purchases infrastructure.

Observer mode.

iOS.

Adapty Dashboard.

  1. Fill in App Store Connect shared secret in iOS SDK settings.

  2. Update App Store Connect subscription status URL with our link. This way, you'll see subscription events in analytics as soon as they occur.

  3. For analytics and attribution integrations you want to use, provide credentials and event names in Integrations section of the dashboard.

  4. Configure App Store Connect API integration to analyze historical data from App Store and get better predictions.

SDK configuration.

  1. Install Adapty SDK in your app. Make sure you use Public SDK key.

  2. Call Adapty.activate("PUBLIC_SDK_KEY", observerMode: true) method with observerMode set to true. All Adapty SDK calls must be made after calling .activate() method. Otherwise, we won't be able to authenticate requests.

  3. If you have internal user ids, the best way to pass them to Adapty is also .activate() method with customerUserId parameter. If the user id is unknown at the time of calling .activate(), you can set it later using .identify(). If you need to logout a user, use .logout() method.

Profile properties and attribution.

  1. To set profile properties, use .updateProfile() method. You can set analytics ids that will be used in Amplitude, Mixpanel, and AppMetrica. If you haven't set specific profile analytics id, we'll be using customerUserId instead. If customerUserId is not set either, we'll be using our internal profile id.

  2. To pass attribution data to Adapty, use .updateAttribution() method. We support AppsFlyer, Adjust, and Branch. We've provided code snippets to integrate each of them.

Check the integration.

  1. Launch your app. The profile should appear in Profiles section. If you set customerUserId, you should see it in App User ID. You can also search profiles by id. If you don't see the profile, make sure you're calling .activate() method and passing the correct Public SDK key.

  2. Make the purchase. You should see the event on the profile page. If you don't see the event, make sure you've set the correct App Store Connect shared secret in iOS SDK settings.

  3. Check the analytics. If you don't see configured events there, make sure that:

    1. the integration is enabled in Integrations section.

    2. you've provided correct credentials

    3. you've set customerUserId or analytics id using .updateProfile() or .updateAttribution() methods. Also, make sure you're setting customerUserId or analytics id before making purchases.

Full mode.

iOS.

Adapty Dashboard.

  1. Fill in App Store Connect shared secret in iOS SDK settings.

  2. Update App Store Connect subscription status URL with our link. This way, you'll see subscription events in analytics as soon as they occur.

  3. For analytics and attribution integrations you want to use, provide credentials and event names in Integrations section of the dashboard.

  4. Create products, paywalls, and A/B tests in Subscriptions section. Make sure to assign the products to correct product sets (monthly, yearly, lifetime, etc.) and paid access levels (standard is suitable for most cases).

  5. If you use promo campaigns, upload push certificates in iOS SDK settings.

  6. If you use subscription offers, upload the subscription key in iOS SDK settings.

  7. Configure App Store Connect API integration to analyze historical data from App Store and get better predictions.

SDK configuration.

  1. Install Adapty SDK in your app. Make sure you use Public SDK key.

  2. Call Adapty.activate("PUBLIC_SDK_KEY") method with observerMode set to false or not set. All Adapty SDK calls must be made after calling .activate() method. Otherwise, we won't be able to authenticate requests.

  3. If you have internal user ids, the best way to pass them to Adapty is also .activate() method with customerUserId parameter. If the user id is unknown at the time of calling .activate(), you can set it later using .identify(). If you need to logout a user, use .logout() method.

Profile properties and attribution.

  1. To set profile properties, use .updateProfile() method. You can set analytics ids that will be used in Amplitude, Mixpanel, and AppMetrica. If you haven't set specific profile analytics id, we'll be using customerUserId instead. If customerUserId is not set either, we'll be using our internal profile id.

  2. To pass attribution data to Adapty, use .updateAttribution() method. We support AppsFlyer, Adjust, and Branch. We've provided code snippets to integrate each of them.

Purchases and A/B tests.

  1. Call .getPaywalls() to get the list of paywalls within A/B tests configured in Adapty Dashboard. This method returns just one specific variation based on the weight and targeting, so you don't have to do it on your side. You can then display the products. Adapty product object has all the properties you need to display it, so you don't have to use SKProduct. You can also find some useful properties – like localized price, subscription and discount periods, eligibility for subscription, and introductory offers.

  2. To make the purchase, use .makePurchase() method, passing Adapty product, and optionally offer id. The response will contain Apple raw response and processed subscription and access level data (we'll talk about them in the next section).

  3. To restore purchases, use .restorePurchases().

  4. To display visual paywall configured in Adapty Dashboard, use .showPaywall() method.

Access levels.

  1. To get the user's access level, use getPurchaserInfo(). Most of the time you can just use isActive property of access level to check whether the user has an active subscription or not. You can also check the list of subscription and non-subscription objects.

  2. You can listen for subscription updates using didReceiveUpdatedPurchaserInfo() delegate method.

Promo campaigns.

  1. To use promo campaigns, you need to pass push notification to Adapty SDK using .handlePushNotification() method. Check out this code snippet.

  2. To get a promo for the user, call getPromo(). It might be empty if there's no promo available for the user.

  3. You can listen for promo updates using didReceivePromo() delegate method.

Check the integration.

  1. Launch your app. The profile should appear in Profiles section. If you set customerUserId, you should see it in App User ID. You can also search profiles by id. If you don't see the profile, make sure you're calling .activate() method and passing the correct Public SDK key.

  2. Display the products on the paywall. If there're no products visible, check that:

    1. you've created the products, paywalls, and A/B tests in Subscriptions section;

    2. you're using developerId configured in the dashboard;

    3. you're using App Store Connect sandbox account with access to a specific app.

  3. Make the purchase. You should see the event on the profile page. If you don't see the event, make sure you've set the correct App Store Connect shared secret in iOS SDK settings and that observerMode set to false or not set.

  4. Check the analytics. If you don't see configured events there, make sure that:

    1. the integration is enabled in Integrations section.

    2. you've provided correct credentials

    3. you've set customerUserId or analytics id using .updateProfile() or .updateAttribution() methods. Also, make sure you're setting customerUserId or analytics id before making purchases.

  5. Create a promo campaign. You can create a cohort with just your profile for testing. Click send now and you should receive a push notification with selected promo. If you haven't received a push, make sure that:

    1. you've uploaded a valid push certificate;

    2. you gave permission to push notifications in your app;

    3. you're targeting the right audience in the cohort;

    4. you're passing push notification to Adapty SDK using .handlePushNotification() method.

    Keep in mind, that by default profile can only receive one push notification per day, and 1 push notification per month from the same promo campaign.

If you have any questions about integrating Adapty SDK, feel free to contact us at support@adapty.io.