Initialization and Identification

Basic Initialization

By default, Apphud SDK creates own unique UUID user identifiers for each device. On iOS, User ID is saved to keychain and persists after app reinstall, however on Android User ID is reset after each reinstall due to technical limitations. If you want Apphud to manage User ID for you (recommended), then just initialize SDK without passing any User ID. Apphud guarantees User ID uniqueness for each device.
Basic Initialization looks like this:

Apphud.start(apiKey: "YOUR_API_KEY")
[Apphud startWithApiKey:@"YOUR_API_KEY" userID:nil observerMode:NO];
Apphud.start(this, "YOUR_API_KEY")
await Apphud.start(apiKey: "YOUR_API_KEY", observerMode: false);
await ApphudSdk.start({ apiKey: "YOUR_API_KEY" });

Custom User ID

If you have your own User ID management logic, you can set custom User ID. You are responsible for User ID uniqueness in this case.

Apphud.start(apiKey: "YOUR_API_KEY", userID: "YOUR_USER_ID")
[Apphud startWithApiKey:@"YOUR_API_KEY" userID:@"YOUR_USER_ID" observerMode:NO];
Apphud.start(this, "YOUR_API_KEY", "YOUR_USER_ID")
await Apphud.start(apiKey: "YOUR_API_KEY", userID: "YOUR_USER_ID", observerMode: false);
await ApphudSdk.start({ apiKey: "YOUR_API_KEY", userId: "YOUR_USER_ID", observerMode: false });

Custom Device ID

You can also initialise SDK with custom Device ID. This should be used if you plan to use logout / login features. You are responsible for User ID uniqueness and User Merging in this case. Best practice is to pass the same identifier to Device ID and User ID:

Apphud.startManually(apiKey: "YOUR_API_KEY", userID: "YOUR_USER_ID", deviceID: "YOUR_USER_ID")
[Apphud startManuallyWithApiKey:"YOUR_API_KEY" userID:@"YOUR_USER_ID" deviceID:@"YOUR_USER_ID" observerMode:NO];
Apphud.startManually(this, "YOUR_API_KEY", "YOUR_USER_ID", "YOUR_USER_ID")
await Apphud.startManually(apiKey: "YOUR_API_KEY", userID: "YOUR_USER_ID", deviceID: "YOUR_USER_ID", observerMode: false);
await ApphudSdk.startManually(apiKey: "YOUR_API_KEY", userId: "YOUR_USER_ID", deviceId: "YOUR_USER_ID", observerMode: false);

Collect Device Identifiers (Android)

For Android SDK 1.8.0 or higher, Advertising Identifier is not collected automatically. You must manually call Apphud.collectDeviceIdentifiers() method after SDK initialization. Collecting device identifiers is required for marketing attribution providers, like AppsFlyer, Adjust, Singular, etc.
When targeting Android 13 and above, you must also declare AD_ID permission in the manifest file.

Apphud.collectDeviceIdentifiers()

Observer Mode

If you want to handle purchases by yourself, you can add Apphud in Observer (Analytics) Mode.
Get more information in our Observer Mode guide.

❗️

Important Note

When observerMode is true, Apphud SDK will not finish (acknowledge) transactions automatically. You are responsible for finishing transactions (iOS) or acknowledging purchases (Android).

Update User ID

You can update your user's ID at any time after SDK initialization. This can be useful if you get your User ID some time after launch.

Apphud.updateUserID("YOUR_USER_ID")

Log Out

Log out method will clear all saved data and reset SDK to uninitialised state. You must initialize SDK again after this method call. Use this method if you have your own login-logout logic.

Apphud.logout()
Apphud.logout()
[Apphud logout];
await Apphud.logout()
await ApphudSdk.logout();

Cross Platform Support

If you have both iOS and Android apps you should decide whether you need cross platform support or not. This is basically means adding both platforms in one Apphud app rather than creating two different apps for each platform. Cross platform support has prons and cons.

📘

Cross-platform Note

If you use cross platform Apphud app, then User ID will be the main user identifier across both apps.

When you should choose cross platform support?

If you added both platforms in one app, you will get:

  • Ability to have single subscription per user. If you have your own login system, you can use Apphud for cross-platform subscription support. If user purchases subscription on iOS, he will get that premium subscription on Android as well (if Apphud SDK started with the same user id).
  • One dashboard for both apps. You will be able to see summarised revenue in dashboard and charts.

When you should NOT choose cross platform support?

  • You don't have login system in your apps. So users from two platforms can't be merged.
  • You don't want Android app revenue to be shared with iOS app revenue. This might be useful, if you have different Apphud Members on each platform.
  • You don't want to have universal dashboard or charts.

User Merging

iOS

By default, users are being merged only if their App Store Receipts match. For example, if Apphud has a customer A with App Store Receipt A and we receive a new request from customer B with App Store Receipt A, then both customers are merged into customer A and User ID of the latter one is changed to A.
In other words, Apphud merges users by their original transaction id.

Android

By default, users are being merged only if their Google Play purchase tokens match. For example, if Apphud has a customer A with Google Play purchase token A and we receive a new request from customer B with Google Play purchase token A, then both customers are merged into customer A and User ID of the latter one is changed to A.
In other words, Apphud merges users with their Google Play purchase tokens.

User Uniqueness

iOS

The device ID is the main identifier that uniquely identifies a customer. So even if you initialize SDK with the same custom User ID on different devices, several new users with the same User ID will be created since they have different Device IDs.

📘

iOS Note

Device ID is also being saved to Keychain, so even if you delete the app, the old device ID will be restored as well as user info.
To test a fresh install see this guide.

If you still would like to use your custom User ID as a unique identifier across the app, you should use Apphud.startManually method. Passing the same ID to the userID and deviceID fields will guarantee that the same user will be returned in case of passing the same User IDs on multiple devices.

Android

User ID is the main identifier that uniquely identifies a customer. So if you initialize SDK with a different User ID on the same device, a new user will be created. It is recommended to use the Apphud login system (not passing any userID at all).

🚧

Android Note

As known, Android does not have Keychain, so re-installing the app will cause a new fresh user to be created.

If you still would like to use your custom User ID as unique identifier across the app, just pass your User ID when initialising the app. See the top of this guide for examples.


What’s Next