Users and Devices

User IDs

When Leanplum start is called for the first time on a device, a new user profile is created and Leanplum starts tracking activity and sessions for this user. If no custom User ID is sent with the start call, the User ID value is set to the Device ID.

If, however, you have your own concept of User IDs, you can pass a User ID in the start call. This way, if the user has multiple devices, we will count them as the same user and merge their profiles.

Leanplum.start(this, "user1234");
[Leanplum startWithUserId:@"user1234"];
Leanplum.start(withUserId: "user1234")

// Start with user ID and attributes.
Leanplum.start('user1234', {'gender': 'Female'});

You can also set the User ID after start. See more below.


Passing a user ID with start may not work well if you have a login system. You should still call start early on to track user activity, but then set the user ID later on with setUserId when the user logs in.

[Leanplum setUserId:@"user1234"];

// Set user attributes and ID at the same time.
Leanplum.setUserAttributes('user1234', {'gender': 'Female'});

When the user ID is set for the first time on a device, the existing profile in Leanplum is updated with that user ID and all previously tracked data remains. After this first setUserId call, each subsequent call that includes a different ID will end the current User session, and create a new session for the new User. If the new User ID doesn't exist, a new User Profile will be created in Leanplum.

Here's how setting the user ID with setUserId works with typical registration and login scenarios:

  • Register: If a user ID has not been set on this device yet and the supplied user ID does not exist, Leanplum will update the current user profile (created on start) with the supplied user ID (replacing the device ID).
  • Login: If a user ID has not been set on this device yet and the supplied user ID does exist, the current and existing user profiles will be merged. This ensures that users with multiple devices are tracked as one user. If the same user logs back in on this device, no changes will be made to their profile since their User ID is already set.
  • Switch user: If a user ID has been set on this device and the supplied user ID is different, the current session will be ended and a new session will be started for the supplied user ID. A user with the supplied user ID will be created if one does not already exist.


Leanplum will not end the session after a user logs out, and does not include any methods to do so; all user activity is tracked and attributed to the last logged-in user (set by the setUserId call). This allows you to track activity in your app even while the user is logged out.

If you want to keep track of which users are logged in and which are logged out, set a user attribute (e.g. logged_in).

Do not set a different user ID to handle logouts. This will create a new user profile in Leanplum and start a new session for them, which will skew your analytics.

Device IDs

The device ID uniquely identifies the devices and is determined automatically by the SDK. On Unity, we use SystemInfo.deviceUniqueIdentifier to get the device ID. Refer to the Unity documentation to learn more.

User Attributes

A user attribute is any piece of data associated with a user that you provide to the SDK. Each session has its own user attributes, but they get copied from one session to the next. This is in contrast to event parameters, which may take on different values per event. For this reason, you generally use user attributes for things that do not change much within the session, or with which you want the entire session associated.


  • Personalizing content (variables, messages, resources, and interfaces) to different types of users.
  • Targeting an A/B test.
  • Filtering reports by a particular user attribute, like only looking at data for "whales".
  • Grouping reports (constructing a bar graph or histogram), by different attribute values. E.g. Create a histogram of average session length by number of friends.


  • Gender
  • Age
  • Number of friends
  • User interests


  • Up to 200 attributes may be defined for your app.
  • Attribute names must be strings, and values must be strings or numbers.
  • Attribute values will be the same across all events and states in a particular session.
// Passing attributes at session start allows us to target content based on the attributes.
Dictionary<string, object> attributes = new Dictionary<string, object>();
attributes.Add("gender", "Female");
attributes.Add("age", 29);

// You can also pass them later on in the session, but you won't be able to
// target variables or messages at these for that session.

// Clear the attributes.
attributes.Add("gender", null);
attributes.Add("age", null);