User Identifiers

User identification is essential for a mobile application with an in-app subscription. Each subscriber should have a User ID that identifies them within your app. With Qonversion, you can use different ways to identify your users within the app based on your requirements.

1. Qonversion User ID

Qonversion creates a unique User ID each time an app is installed and opened for the first time. To use Qonversion User ID, call the userInfo method. You can use Qonversion User ID for third-party integrations or other purposes like matching data from webhook notifications to your server.

Qonversion.shared().userInfo { user, error in
  // use user?.qonversionId
}

[[Qonversion sharedInstance] userInfo:^(QONUser * _Nullable user, NSError * _Nullable error) {
  // use [user qonversionId] if no error occurred
}]

Qonversion.getSharedInstance().userInfo(new QonversionUserCallback() {
    @Override
    public void onSuccess(@NonNull QUser user) {
        // use user.getQonversionId()
    }

    @Override
    public void onError(@NonNull QonversionError error) {
        // handle error here
    }
});

Qonversion.shared.userInfo(object : QonversionUserCallback {
    override fun onSuccess(user: QUser) {
        // use user.qonversionId
    }

    override fun onError(error: QonversionError) {
        // handle error here
    }
})

try {
  final userInfo = await Qonversion.getSharedInstance().userInfo();
  // use userInfo.qonversionId
} catch (e) {
  // handle error here
}

try {
  const userInfo = await Qonversion.getSharedInstance().userInfo();
  // use userInfo.qonversionId
} catch (e) {
  // handle error here
}

Qonversion.GetSharedInstance().UserInfo((userInfo, error) =>
{
    if (error == null)
    {
        // use userInfo.QonversionId
    }
    else
    {
        // Handle the error
        Debug.Log("Error" + error.ToString());
    }
});

try {
  const userInfo = await Qonversion.getSharedInstance().userInfo();
  // use userInfo.qonversionId
} catch (e) {
  // handle error here
}

try {
  const userInfo = await Qonversion.getSharedInstance().userInfo();
  // use userInfo.qonversionId
} catch (e) {
  // handle error here
}

curl --location --request GET 'https://api.qonversion.io/v3/users/QON_38a2d811afd54a433587620f8696266e' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY'

{"created":1658489733000,"environment":"prod","id":"QON_38a2d811afd54a433587620f8696266e","identity_id":"your_custom_user_id"}

2. User ID for third-party Integrations

Qonversion SDK provides an asynchronous method to set your user ID, which will later be sent to third-party integrations you enabled.

Qonversion.shared().setUserProperty(.userID, value: "yourSideUserId")

[[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyUserID value:@"yourSideUserId"];

Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.CustomUserId, "yourSideUserID");

Qonversion.shared.setUserProperty(QUserPropertyKey.CustomUserId, "yourSideUserID")

Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.customUserId, 'yourSideUserId');

Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.CUSTOM_USER_ID, 'yourSideUserId');

Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.CustomUserId, "yourSideUserId");

Qonversion.getSharedInstance().setUserProperty(Qonversion.UserPropertyKey.CUSTOM_USER_ID, 'yourSideUserId');

Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.CUSTOM_USER_ID, 'yourSideUserId');

Use User ID for third-party Integrations to attribute events to existing users in other platforms. For managing user access across multiple devices or Apple and Google app stores, use User Identifiers.

3. User Identity

User Identity allows cross-device & cross-platform user identification and access management.

Use the documentation below and the User Identity concept only if you want to manage user access across multiple devices or Apple, Google and Web platforms for users logged into their accounts within your apps.If you need to assign your user ID for analytical purposes, use the setUserProperty() method described above.

User identification is critical in building cross-platform apps where you want to manage user access based on payments across different platforms. This can be a complex task as users can log in and out of your application, use multiple devices, or reinstall the app. To provide flexible subscription infrastructure and consistent data, we have built a comprehensive solution using a combination of Qonversion IDs, your backend IDs, and the merging concept for users. Qonversion lets you identify your signed-in users and unlock premium access across multiple devices. Use the identify() method to link a user to your signed-in subscriber. Call this method every time you want to use User Identity. For example, when a user logs in. User Identity provides a convenient way of managing premium access of your existing subscribers, including the following cases:

A user reinstalls your app for any reason. Using the same User ID allows you to provide premium access linked to previously purchased products.
A user logs in on several devices. You can provide premium access based on a subscription purchased on one of his devices.
A user logs in on iOS and Android versions of your app. You can provide premium access based on a subscription purchased on one of the platforms.

Logging in

When a user logs into his account, call identify().

Qonversion.shared().identify("your_custom_user_id")

// or the following option, if you want to get notified about the result.

Qonversion.shared().identify("your_custom_user_id") { user, error in
  // use user if necessary
}

[[Qonversion sharedInstance] identify:@"your_custom_user_id"];

// or the following option, if you want to get notified about the result.

[[Qonversion sharedInstance] identify:@"your_custom_user_id" completion:^(QONUser * _Nullable user, NSError * _Nullable error) {
  // use user if necessary
}];

Qonversion.getSharedInstance().identify("your_custom_user_id");

// or the following option, if you want to get notified about the result.

Qonversion.getSharedInstance().identify("your_custom_user_id", new QonversionUserCallback() {
    @Override
    public void onSuccess(@NonNull QUser user) {
        // use user if necessary
    }

    @Override
    public void onError(@NonNull QonversionError error) {
        // handle error here
    }
});

Qonversion.shared.identify("your_custom_user_id")

// or the following option, if you want to get notified about the result.

Qonversion.shared.identify("your_custom_user_id", object : QonversionUserCallback {
    override fun onSuccess(user: QUser) {
        // use user if necessary
    }

    override fun onError(error: QonversionError) {
        // handle error here
    }
})

try {
  final userInfo = await Qonversion.getSharedInstance().identify("your_custom_user_id");
  // use userInfo if necessary
} catch (e) {
  // handle error here
}

try {
  const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
  // use userInfo if necessary
} catch (e) {
  // handle error here
}

Qonversion.GetSharedInstance().Identify("your_custom_user_id")

// or the following option, if you want to get notified about the result.

Qonversion.GetSharedInstance().Identify("your_custom_user_id", (userInfo, error) =>
{
    if (error == null)
    {
        // use userInfo if necessary
    }
    else
    {
        // Handle the error
        Debug.Log("Error" + error.ToString());
    }
});

try {
  const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
  // use userInfo if necessary
} catch (e) {
  // handle error here
}

try {
  const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
  // use userInfo if necessary
} catch (e) {
  // handle error here
}

curl --location --request POST 'https://api.qonversion.io/v3/identities/new_identities_user' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "QON_38a2d811afd54a433587620f8696266e"
}'

{
    "id": "new_identities_user",
    "user_id": "QON_38a2d811afd54a433587620f8696266e"
}

Always use unique user ID values. Otherwise, a user can get matched to another user’s premium status.

To check entitlements for identified users, you can call checkEntitlements(). You can check the details of setting up entitlements here.

Logging out

You need to call the logout() method to handle entitlements for an unauthorized user. Call this method when a user logs out within your app:

Qonversion.shared().logout()

[[Qonversion sharedInstance] logout];

Qonversion.getSharedInstance().logout();

Qonversion.shared.logout()

Qonversion.getSharedInstance().logout();

Qonversion.getSharedInstance().logout();

Qonversion.GetSharedInstance().Logout();

Qonversion.getSharedInstance().logout();

Qonversion.getSharedInstance().logout();

When a user logs back into his account, don’t forget to useidentify() method again.

Examples

Let’s look at the following examples to understand better Qonversion.identify().

In the following examples:

Anonymous ID corresponds to the same app store account (Apple or Google).
A and B correspond to two different app store accounts (Apple or Google).

Example 1. No User Identity.

Two anonymous users install the app using separate devices and subscribe without using theidentify() method. These users have not been linked to each other.

Anonymous ID	User ID	Action
A	null	Install
B	null	Install
B	null	Start Subscription X -> Gets Entitlement X
A	null	Start Subscription Y -> Gets Entitlement Y

Now let’s look at the identify() way of usage.