Initialization and Identification

Basic Initialization

For most cases, allowing Apphud to manage the User ID is recommended. To do this, just do not provide any custom User ID in the Apphud.start(...) method. Apphud SDK ensures the uniqueness of the User ID for each device, maintaining individual user identification and preventing duplication of User ID values.

SDK automatically generates a unique UUID as the User ID for each device. On iOS, the User ID is stored in the keychain, ensuring it remains consistent even after an app is reinstalled. Conversely, on Android, the User ID is reset with each new installation due to platform-specific limitations.

Basic Initialization should be as following:

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" });

ApphudSDK.Start("YOUR_API_KEY", (ApphudUser user) => { });

Primary Identifier

For all Android apps, for all cross-platform apps, and any new apps created after February 15, 2024, the Primary Identifier is User ID.
For iOS-only apps created before this date, the primary identifier was the Device ID.
If you do not pass custom User ID during , you should nothing to do with it.
Otherwise, if you pass custom User ID, then it is developer's reponsibility for providing unique values.

Custom User ID

📘

User ID must be unique

If you pass custom User ID that already exists in the system, your current app installation will be linked to the existing user record.

If you have your own User ID management logic, you can set custom User ID. Developers are responsible for ensuring the uniqueness of any custom User IDs passed to the Apphud initialization method.

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 });

ApphudSDK.Start("YOUR_API_KEY", "some user id", (ApphudUser user) => { });

Passing Another User ID on the Same Device

Developers are responsible for ensuring the uniqueness of any custom User IDs passed to the Apphud initialization method. When a different User ID is submitted on the same device during a relaunch or reinstall:

• Apphud first attempts to locate an existing user record associated with that User ID. If found, the current installation is linked to the identified user.
• If no matching user record is found, Apphud safely updates the User ID.
• For iOS-exclusive apps created before February 15, 2024, the primary user identifier was the Device ID, so providing different User ID will safely update the 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);

Updating the User ID

Developers can modify the User's ID at any point after the SDK has been initialized. This feature is particularly helpful if the unique User ID becomes available only after the app has been launched. It is crucial that developers ensure the new User ID is unique to avoid conflicts.

If an attempt is made to update the user identifier to one that already exists within the system, the SDK will retrieve the corresponding existing user record. This may result in unexpected consequences, such as changes in the user's premium access status, changes to available paywalls or placements, etc. If no user record was found with the new User ID, the system will safely update the User ID for the current user.

To update the User ID, use the following code:

Apphud.updateUserID("YOUR_USER_ID")

Log Out

The log out method removes all saved data and reverts the SDK to an uninitialized state. After invoking this method, the SDK must be re-initialized for further use.

This method should be used exclusively in scenarios where the app incorporates its own login-logout mechanisms and a custom User ID is specified during the SDK initialization process.

Apphud.logout()

Apphud.logout()

[Apphud logout];

await Apphud.logout()

await ApphudSdk.logout();

ApphudSDK.LogOut();

Custom Device ID

You should only use this method for iOS-exclusive apps created before February 15, 2024 as part of your custom login-logout logic. Do this at your own risk.

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);

User Merging

The system merges user accounts based on their purchase history. When a user installs the app on a new device using the same Google or Apple account, a new user record is typically created. However, if purchases are restored, this process changes.

Apphud identifies any purchase records linked to the new user's Google or Apple account. If such a record exists, Apphud restores the original user record and removes the newly created one from the database. In this event, the SDK triggers the apphudDidChangeUserID delegate method as part of the Restore Purchases response.

👍

Automatic Purchase Restoring

Please note, the SDK automatically restores purchase history starting from version 2.8.8 for iOS SDK, version 2.5.0 for Android SDK, and for other cross-platform SDKs that depend on these native SDK versions.

For instance, if Apphud recognizes a new installation from Customer B who shares the same Google or Apple account as existing Customer A, both customer records are merged. The user ID for Customer B is updated to match Customer A's, prioritizing the original user’s information.

New Users Tracking

How does Apphud track App Installs?

In dashboard and charts Apphud counts only production users (App Store / Google Play installs), and skips sandbox users (like simulator installs, Testflight builds, Internal Google Play releases, etc.).
To view sandbox users, you can go to Users tab and toggle the "View sandbox users" switcher.

Apphud tracks new users who are directly interacting with the SDK and anonymous users who are tracked via server notifications after making a purchase in an app that does not contain the Apphud SDK. In both instances, users are recognized and counted as new users.

App Install date is based on User's "First Seen At" date field. Read more on how Apphud calculates user's first seen date here.

Reinstalls Tracking

📘

Important

Reinstalls tracking is supported on iOS SDK 3.0.1 or higher, Android SDK 2.5.0 or higher, and other cross-platform SDKs that depend on these native SDK versions or higher.

Apphud identifies new users based on the first session recorded for each new app installation.

For iOS apps, reinstall is tracked by comparing Device ID value from the keychain.

For Android apps, reinstall is tracked by comparing Android ID value.

For iOS and Android Apps reinstalls do not create a new user record.

A reinstall event is generated based on the following conditions:

1. There must be a minimum of 2 minutes between the initial install and the reinstall, and the next app launch must occur within 30 days of the reinstall. If these conditions are not met, the reinstall event will be ignored.
2. The Apphud.start(...)method should be used, so the event is triggered;startManually method should not be used.

For Android apps with SDK v2.5.0 or lower, reinstalls are not tracked, and typically considered a new user, except in instances where a paid user successfully restores their previous purchases.

First Seen At

Most charts in the Apphud dashboard utilize the user's first seen date rather than the "user created" date.

First Seen Date – This is the date when the app was installed. The SDK determines this by fetching the creation date of the app folder and passes this date during user registration. If the first seen date is earlier than the first launch date, the earlier date is used as the first seen date.

However, in some instances, the app installation date may not be available or accurate (for example, if the app was reinstalled, we cannot track the original installation date). In such cases, we use the earliest date among the following three values: user created date, app installation date, or the date of the first in-app purchase.

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.

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).

User Identification and Merging for Legacy iOS apps

For iOS-exclusive apps created before February 15, 2024, the primary user identifier is the Device ID.

Here is the user identification logic for these older apps:

• If a different User ID is provided on the same device, the system will update the existing user record with the new User ID, even if there is existing User ID record. User ID is not unique identifier for these apps.