Identifying Users

Supported on ios-logo android-logo rest-logo react-logo js-logo java-logo node-logo python-logo roku-logo

With Apptimize, you have the ability to identify your users with the Customer User ID API and ensure that a consistent experience is delivered to them across all platforms and devices. Identifying users also enables you to track those users across platforms and measure the impact of changes on one platform to actions taken on another.

  • Client-side - Mobile/Web SDKs (Android, iOS, JavaScript, React Native): the User ID is optional and it is a best practice to set it on the user’s first log-in to ensure consistency thereafter

  • Server-side SDKs, REST, and Roku (Node.js, Java, Python, REST API, Roku): the User ID is mandatory for server-side calls to work as it is expected as a parameter in server-side methods

Customer User ID vs. Pilot Targeting ID

It is important to note that Apptimize supports two different APIs related to identifying users or devices:

  • The Customer User ID API is used to identify a specific user across platforms and devices. When a user ID is set using this API, all activity (experiment participation, events) will be aggregated to this single user, and we will ensure that the user is allocated into the same variant across platforms. If this API is not used, Apptimize will assign an anonymous ID to each client-side device.

  • The Pilot Targeting API is used to target a specific set of devices or users with the Groups functionality on client-side SDKs (Android, iOS, JavaScript, React Native) and REST API. In cases where you want a specific group of devices (for example, a QA group, internal staging group, or external beta users) to see a specific Feature Flag or Experiment, you can identify the device using the Pilot Targeting API.

These APIs can both be used on a given implementation, but it is important to understand the difference. Please contact Apptimize if you have questions about your setup.

Identifying Users on the Client-Side

For every Experiment or Feature Flag that is to be executed, Apptimize first checks if the user has been identified with a User ID. The User ID is used for bucketing and ensuring that the experience is consistent for the user across platforms, and so we strongly recommend setting the User ID once it is known. You can set and get the User ID with the following methods:

Android (Java)
// Sets the user ID to the variable passed into setCustomerUserId
// Apptimize will use the Anonymous ID for allocation until this property is set

// Returns the String userID if set, returns null if not set

Important note: Setting the User ID will clear any previously defined custom attributes for the device. This is because we can’t be sure that the previously defined attributes still apply to this newly logged-in user. Make sure you set any custom attributes associated with a User ID after the user has been identified.

Remember, if you are planning to use the Groups functionality to assign a Feature Flag or target an Experiment to specific devices, you must implement the Pilot Targeting API.

Apptimize assigns a randomly-generated Anonymous ID to the device by default. So, when the User ID is not specified or unknown, the Anonymous ID is used to determine allocation instead. Once a User ID is set, the Anonymous ID is no longer used for allocation 1; however, any previously allocated variants/experiences that the user had seen while anonymous will persist. If you need to know the value of the Anonymous ID at any point, use the following get method:

Android (Java)
// Returns the Anonymous ID

Back-Population of Anonymous Activity

When a device is identified using setCustomerUserId, Apptimize will associate prior activity (experiment participation, tracked events) from the anonymous device with the provided userId. This enables us to seamlessly support experiments that span both logged-in and logged-out states (for example, an experiment impacting the user on-boarding flow). If the userId is cleared, we will stop associating activity from that device to the userId and will treat all activity from that point forward as belonging to an anonymous device.

Server-Side Methods

On the server-side, the REST API and Roku SDK, since there is no persistent state, you do not set and get the User ID as in the client-side examples above. Instead you must pass the User ID to all calls that require it. See Events, Code Block Experiments, and Dynamic Variable Experiments for examples.

Analyzing Results

Apptimize automatically bundles a user’s results based on the User ID across all platforms. In your Experiment Results, you are also able to filter users by their platform activity.


Please see our Results documentation for more information on how to interpret your results. If you have any questions, reach out to


The Anonymous ID is still stored, and the User ID can be set to null if you wish to revert allocation to be based on the Anonymous ID instead of the User ID.