Requirements

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

Installation

Apphud SDK can be installed via CocoaPods, Carthage, Swift Package Manager or manually.

Install via CocoaPods

Add the following line to your Podfile:

pod 'ApphudSDK'

Install via Carthage

Add the following line to your Cartfile:

github "apphud/ApphudSDK"

And then run in the Terminal:

carthage update

Install via Swift Package Manager

Add package dependency with the following URL:

https://github.com/apphud/ApphudSDK

Manual Installation

Copy all files from ApphudSDK folder to your project from this link.

Configure Apphud SDK

Integration process consists of following parts:

• ​Initialize SDK​

• ​Configure push notifications​

• ​Handle in-app purchases​

• ​Read In-App Purchase Testing Tips​

• ​Handle promoted in-app purchases​

• ​Migrate existing subscribers (for live apps)​

• ​Set up analytics integrations (iOS part)​

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:

import ApphudSDK
​
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
​
  Apphud.setFinishAllTransactions() // Add if using SDK in purchase mode
  Apphud.start(apiKey: "YOUR_SDK_TOKEN")
​
  // the rest of your code
  return true
}

#import <ApphudSDK-Swift.h>
​
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    [Apphud setFinishAllTransactions]; // Add if using SDK in purchase mode
    
    // 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 In-App Purchases

Apphud SDK provides a set of methods to manage subscriptions and non-renewing purchases. All these methods can be used regardless of how you purchased the product (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:

Apphud.products()

[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 and a callback block, if set. So use whatever you want.

Make a Purchase

To make a purchase call:

Apphud.purchase(product) { result in
   if let subscription = result.subscription, subscription.isActive(){
      // has active subscription
   } else if let purchase = result.nonRenewingPurchase, purchase.isActive(){
      // has active non-renewing purchase
   } else {
      // handle error or check transaction status.
   }
}

[Apphud purchase:product callback:^(ApphudPurchaseResult * result) {
    if (result.subcription.isActive){
      // has active subscription
    } else if (result.nonRenewingPurchase.isActive){
      // has active non-renewing purchase
    } else {
      // handle error or check transaction status
    }
}];

This method will return an ApphudPurchaseResult object, which contains subscription model with all info about your subscription. ApphudPurchaseResult may also contain transaction, error and nonRenewingPurchase objects in case user purchased non-renewing purchase. See ApphudPurchaseResult.swift and ApphudSubscription.swift files for details.

You can also read In-App Purchase Testing Tips.

Check Subscription Status

Apphud.hasActiveSubscription()

[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:

Apphud.subscription()

[Apphud subscription];

See ApphudSubscription.swift file for details.

Check Non-renewing Purchase Status

Use this method to check whether the user has purchased in-app purchase and it's not refunded. Returns false if was never purchased or is refunded.

Apphud.isNonRenewingPurchaseActive(productIdentifier: "productID")

[Apphud isNonRenewingPurchaseActiveWithProductIdentifier:@"producID"];

Get Non-renewing Purchase Details

To get non-renewing purchases, which contain purchase date, product identifier and cancellation date, use the following method:

Apphud.nonRenewingPurchases()

[Apphud nonRenewingPurchases];

It will return array of all non-renewing in-app purchases user has ever purchased. In-app purchases are sorted by purchase date.

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:

Apphud.restorePurchases{ subscriptions, purchases, error in 
   if Apphud.hasActiveSubscription(){
     // has active subscription  
   } else {
     // no active subscription found, check non-renewing purchases or error
   }
}

[Apphud restorePurchasesWithCallback:^(NSArray<ApphudSubscription *> * _Nullable subscriptions, NSArray *purchases, NSError * _Nullable error) {
   if (Apphud.hasActiveSubscription){
     // has active subscription
   } else {
     // no active subscription found, check non-renewing purchases or error
   }
   
}];

Basically it just sends App Store Receipt to Apphud and returns subscriptions (or nil, if subscriptions are never purchased), non-renewing purchases (or nil, if there are no any) and an optional error.

Handle Promoted In-App Purchases

If you have in-app purchases that can be purchased directly from the App Store, you should implement a logic to continue a payment in the app.

To continue an in-app purchase transaction initiated from the App Store page, please implement the following ApphudDelegate method:

func apphudShouldStartAppStoreDirectPurchase(_ product: SKProduct) -> ((ApphudPurchaseResult) -> Void) {
    // manage your UI here, show a progress hud, etc.
    let callback : ((ApphudPurchaseResult) -> Void) = { result in 
        // check the result, hide a progress hud, etc.
    }
    return callback
}

- (void (^)(ApphudPurchaseResult * _Nonnull))apphudShouldStartAppStoreDirectPurchase:(SKProduct *)product {
    // manage your UI here, show a progress hud, etc.
    return ^(ApphudPurchaseResult * _Nonnull result) {
        // check the result, hide a progress hud, etc.
    };
}

You must return a callback block which will be called when a payment is finished. If you don't implement this method or return nil then a payment will not start; you can also save the product and return nil to initiate a payment later by yourself. You can also read Apple documentation for details.

Migrate Existing Paying Users

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

// hasPurchases - is your own boolean value indicating that current user is paying user.
if hasPurchases {
    Apphud.migratePurchasesIfNeeded {_, _, _ 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 can see more code samples here. There are two ways to match user identifiers:

Match user identifiers by Apphud's userID (recommended)

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

Apphud.start(apiKey: "YOUR_SDK_TOKEN")
Apphud.setDelegate(self)
​
// Amplitude SDK
Amplitude.instance()?.initializeApiKey("YOUR_AMPLITUDE_API_KEY", userId: Apphud.userID())
​
// Mixpanel SDK
Mixpanel.initialize(token: "mixpanel_token")        
Mixpanel.mainInstance().identify(distinctId: Apphud.userID())

[Apphud startWithApiKey:@"YOUR_SDK_TOKEN" userID:nil];
[Apphud setDelegate:self];
​
// Amplitude SDK
[Amplitude.instance initializeApiKey:@"AMPLITUDE_API_KEY" userId:Apphud.userID];
​
// Mixpanel SDK
[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:

func apphudDidChangeUserID(_ userID: String) {
    // Amplitude SDK
    Amplitude.instance()?.setUserId(userID)
    
    // Mixpanel SDK
    Mixpanel.mainInstance().identify(distinctId: userID)
}

- (void)apphudDidChangeUserID:(NSString *)userID {
    // Amplitude SDK
    [Amplitude.instance setUserId:userID];
    
    // Mixpanel SDK
    [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:

// Initialize Apphud and analytics with your own user id
Apphud.start(apiKey: "YOUR_SDK_TOKEN", userID: "YOUR_OWN_USER_ID")
​
// Amplitude SDK
Amplitude.instance()?.initializeApiKey("YOUR_AMPLITUDE_API_KEY", userId: "YOUR_OWN_USER_ID")
​
// Mixpanel SDK
Mixpanel.initialize(token: "mixpanel_token")        
Mixpanel.mainInstance().identify(distinctId: "YOUR_OWN_USER_ID")

// Initialize Apphud and analytics with your own user id
[Apphud startWithApiKey:@"YOUR_SDK_TOKEN" userID:@"YOUR_OWN_USER_ID"];
​
// Amplitude SDK
[Amplitude.instance initializeApiKey:@"AMPLITUDE_API_KEY" userId:@"YOUR_OWN_USER_ID"];
​
// Mixpanel SDK
[Mixpanel sharedInstanceWithToken:@"MIXPANEL_TOKEN"];
[Mixpanel.sharedInstance identify:@"YOUR_OWN_USER_ID"];

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

// 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")

// After user logged in:
[Apphud updateUserID:@"YOUR_OWN_USER_ID"];
[Amplitude.instance setUserId:@"YOUR_OWN_USER_ID"];
[Mixpanel.sharedInstance identify:@"YOUR_OWN_USER_ID"];

Testing Integrations in Sandbox

To test integrations, ensure that test credentials are provided and make a sandbox in-app purchase.

Apphud will send all subscription events of current user to your test analytics, if test credentials are set in integration settings.

Other

User Eligibility for Introductory Offer

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

// 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
}

// 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:

// 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
}

// 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
}];