SDK Integration

This guide describes how to add Apphud SDK to your iOS app.

Requirements

Apphud SDK requires minimum iOS 11.2 and Xcode 10 and Swift version 4.2.

Installation

Latest SDK version: 0.8. Apphud SDK can be installed via CocoaPods or manually.

Install via CocoaPods

Add the following line to your Podfile:

pod 'ApphudSDK'

In Objective-C project make sure use_frameworks! is added in your Podfile.

And then run in the Terminal:

pod install

Manual Installation

Copy all files in Source folder to your project from this link.

Configure Apphud SDK

Integration process consists of following parts:

Initialize SDK

To initialize Apphud SDK you will need SDK Token. It is a unique identifier of your Apphud application. You can get it in your Apphud application settings under General tab.

Basic initialization looks like this:

Swift
Objective-C
Swift
import ApphudSDK
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
Apphud.start(apiKey: "YOUR_SDK_TOKEN")
// the rest of your code
return true
}
Objective-C
#import <ApphudSDK-Swift.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// pass nil to userID to let Apphud generate it's own userID.
[Apphud startWithApiKey:@"YOUR_SDK_TOKEN" userID:nil];
// the rest of your code
return YES;
}

Configure Push Notifications

Configuring push notifications is highly recommended in order to use Rules – a powerful feature that lets you increase your app revenue by automatically offering a discount to a user at the specified moment.

Handle Subscriptions

If you have a live app and already implemented subscription purchasing, it's not necessary to rewrite your purchase code with Apphud methods. Apphud SDK will still automatically track all purchases in your app.

Apphud SDK provides a set of methods to manage subscriptions. All these methods can be used regardless of how you purchased the subscription (via Apphud SDK or your existing code).

Get StoreKit Products

Apphud automatically fetches SKProduct objects upon launch. Make sure products identifiers are added in Apphud products. To get your products call:

Swift
Objective-C
Swift
Apphud.products()
Objective-C
[Apphud products];

When products are fetched from the App Store you will also receive a notification from Notification Center along with Apphud delegate method call, use what fits better your needs.

Make a Purchase

To make a purchase call:

Swift
Objective-C
Swift
Apphud.purchase(product) { (subscription, error) in
// handle result
}
Objective-C
[Apphud purchase:product callback:^(ApphudSubscription * subscription, NSError * error) {
// handle result
}];

App Store Receipt Submission (Deprecated)

Apphud SDK 0.8 will automatically submit App Store receipt to Apphud whenever user makes a purchase or restores transactions. No additional code required.

For older SDK versions, if you make purchases by yourself, call this method after payment is made:

Swift
Objective-C
Swift
// call this method after successful purchase by yourself
Apphud.submitReceipt("productID") { (subscription, error) in
// handle result
}
Objective-C
// call this method after successful purchase by yourself
[Apphud submitReceipt:@"productID" :^(ApphudSubscription * subscription, NSError * error) {
// handle result
}];

This method will return a subscription model, which contains all relevant info about your subscription, including expiration date. See ApphudSubscription.swift file for details.

Check Subscription Status

Swift
Objective-C
Swift
Apphud.hasActiveSubscription()
Objective-C
[Apphud hasActiveSubscription];

Returns true if user has active subscription. Use this method to determine whether to unlock premium functionality to the user.

Get Subscription Details

To get subscription object (which contains expiration date, autorenewal status, etc.) use the following method:

Swift
Objective-C
Swift
Apphud.subscription()
Objective-C
[Apphud subscription];

See ApphudSubscription.swift file for details.

Restore Purchases

If your app doesn't have a login system, which identifies a premium user by his credentials, then you need a "restore" mechanism. If you already have a "restore purchases" mechanism by calling SKPaymentQueue.default().restoreCompletedTransactions(), then you have nothing to worry about: Apphud SDK will automatically intercept and send the latest App Store Receipt to Apphud servers when your restoration is completed. However, better to call our restore method from SDK:

Swift
Objective-C
Swift
Apphud.restoreSubscriptions{ subscriptions in
// handle here
}
Objective-C
[Apphud restoreSubscriptionsWithCallback:^(NSArray<ApphudSubscription *> * _Nullable subscriptions) {
// handle result
}];

Basically it just sends App Store Receipt to Apphud and returns subscriptions in callback (or nil if nothing was ever purchased).

Migrate Existing Subscribers

If you already have a live app with paying users and you want Apphud to track their subscriptions, you should import their App Store receipts into Apphud. Apphud SDK doesn't automatically submit App Store receipts of your existing subscribers. Run this code at launch of your app:

Swift
Swift
// hasPurchases - is your own boolean value indicating that current user is paying user.
if hasPurchases {
Apphud.migrateSubscriptionsIfNeeded {_ in}
}

Set up Analytics Integrations (iOS part)

If you want to pass subscription events to your analytics services, such as Amplitude or Mixpanel, you need to match user identifiers between Apphud and your analytics.

You don't need to match identifiers in case of AppsFlyer or Branch integration. Check integration guide to your attribution platform.

You can see more code samples here. There are two ways to match user identifiers:

Initialize Apphud first, then initialize your analytics with Apphud User ID:

Swift
Objective-C
Swift
Apphud.start(apiKey: "YOUR_SDK_TOKEN")
Apphud.setDelegate(self)
Amplitude.instance()?.initializeApiKey("YOUR_AMPLITUDE_API_KEY", userId: Apphud.userID())
Mixpanel.initialize(token: "mixpanel_token")
Mixpanel.mainInstance().identify(distinctId: Apphud.userID())
Objective-C
[Apphud startWithApiKey:@"YOUR_SDK_TOKEN" userID:nil];
[Apphud setDelegate:self];
[Amplitude.instance initializeApiKey:@"AMPLITUDE_API_KEY" userId:Apphud.userID];
[Mixpanel sharedInstanceWithToken:@"MIXPANEL_TOKEN"];
[Mixpanel.sharedInstance identify:Apphud.userID];

However, userID may change if user has restored purchases from his another device. You need to implement the following delegate method of ApphudDelegate:

Swift
Objective-C
Swift
func apphudDidChangeUserID(_ userID: String) {
Amplitude.instance()?.setUserId(userID)
Mixpanel.mainInstance().identify(distinctId: userID)
}
Objective-C
- (void)apphudDidChangeUserID:(NSString *)userID {
[Amplitude.instance setUserId:userID];
[Mixpanel.sharedInstance identify:userID];
}

Match user identifiers by your custom userID

Only do this if you are sure that your custom userID explicitly identifies users across their multiple devices. For example, if you have a login system with unique username and password, you can pass username as user ID. The only requirement is to update Apphud userID and your analytics userID simultaneously.

This can be done at app launch:

Swift
Objective-C
Swift
// Initialize Apphud and analytics with your own user id
Apphud.start(apiKey: "YOUR_SDK_TOKEN", userID: "YOUR_OWN_USER_ID")
Amplitude.instance()?.initializeApiKey("YOUR_AMPLITUDE_API_KEY", userId: "YOUR_OWN_USER_ID")
Mixpanel.initialize(token: "mixpanel_token")
Mixpanel.mainInstance().identify(distinctId: "YOUR_OWN_USER_ID")
Objective-C
// Initialize Apphud and analytics with your own user id
[Apphud startWithApiKey:@"YOUR_SDK_TOKEN" userID:@"YOUR_OWN_USER_ID"];
[Amplitude.instance initializeApiKey:@"AMPLITUDE_API_KEY" userId:@"YOUR_OWN_USER_ID"];
[Mixpanel sharedInstanceWithToken:@"MIXPANEL_TOKEN"];
[Mixpanel.sharedInstance identify:@"YOUR_OWN_USER_ID"];

Or you can change userID later. For example, after user logs in:

Swift
Objective-C
Swift
// After user logged in:
Apphud.updateUserID("YOUR_OWN_USER_ID")
Amplitude.instance()?.setUserId("YOUR_OWN_USER_ID")
Mixpanel.mainInstance().identify(distinctId: "YOUR_OWN_USER_ID")
Objective-C
// After user logged in:
[Apphud updateUserID:@"YOUR_OWN_USER_ID"];
[Amplitude.instance setUserId:@"YOUR_OWN_USER_ID"];
[Mixpanel.sharedInstance identify:@"YOUR_OWN_USER_ID"];

Test Integrations

To enable integrations test mode, call before SDK initialization:

Swift
Objective-C
Swift
Apphud.setIntegrationsTestMode()
Objective-C
[Apphud setIntegrationsTestMode];

Do not forget to remove this line before release!

Apphud will send all subscription events of current user to your test analytics, if test API keys are set in integrations dashboard.

Other

User Eligibility for Introductory Offer

You can use Apphud to determine if user is eligible for introductory offer:

Swift
Objective-C
Swift
// Check eligibility for introductory offer
Apphud.checkEligibilityForIntroductoryOffer(product: myProduct) { result in
// handle result
}
// Check eligibility for multiple products at one call
Apphud.checkEligibilitiesForIntroductoryOffers(products: products) { resultDict in
// handle result
}
Objective-C
// Check eligibility for introductory offer
[Apphud checkEligibilityForIntroductoryOfferWithProduct:myProduct callback:^(BOOL eligible) {
// handle result
}];
// Check eligibility for multiple products at one call
[Apphud checkEligibilitiesForIntroductoryOffersWithProducts:productsArray callback:^(NSDictionary * resultDict) {
// handle result
}];

User Eligibility for Promotional Offer

You can also use Apphud to determine if user is eligible for promotional offer:

Swift
Objective-C
Swift
// Check eligibility for promotional offer
Apphud.checkEligibilityForPromotionalOffer(product: myProduct) { result in
// handle result
}
// Check eligibility for multiple products at one call
Apphud.checkEligibilitiesForPromotionalOffers(products: products) { resultDict in
// handle result
}
Objective-C
// Check eligibility for promotional offer
[Apphud checkEligibilityForPromotionalOfferWithProduct:myProduct callback:^(BOOL eligible) {
// handle result
}];
// Check eligibility for multiple products at one call
[Apphud checkEligibilitiesForPromotionalOffersWithProducts:productsArray callback:^(NSDictionary * resultDict) {
// handle result
}];