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 iOS, by default, we use the identifierForVendor. If the device is pre-iOS 6, we use a hash of the MAC address, and in development mode, we use the advertising identifier.

You can choose how the device ID is set the first time start is called on that device by calling one of these before start:

  • LEANPLUM_USE_ADVERTISING_ID: a macro that uses the advertising identifier.
  • [Leanplum setDeviceId:@"customAndUniqueId"]: Sets the device ID to a custom ID. Make sure that your custom ID is unique per device.

Note: The deviceId is set when [Leanplum start]; runs for the first time on that device. After this, it cannot be changed unless the user completely uninstalls and reinstalls your app.

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.
[Leanplum startWithUserAttributes:@{@"gender": @"Female", @"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.
[Leanplum setUserAttributes:@{@"gender": @"Female", @"age": @29}];

// Clear an attribute.
[Leanplum startWithUserAttributes:@{@"gender": [NSNull null]}];
// Passing attributes at session start allows us to target content based on the attributes.
Leanplum.start(userAttributes: ["gender":"Female", "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.
Leanplum.setUserAttributes(["gender":"Female", "age": 29])

// Clear an attribute.
Leanplum.start(userAttributes: ["gender":NSNull()])

User Location

By default, Leanplum uses IP-based geolocation for all users. In addition, the Leanplum SDK also captures GPS/Cell-based geolocation from the user's device if available. GPS/Cell-based information is always trusted more; when available, we use the latitude/longitude coordinates from the device and use reverse-geocoding to determine the name of the Country, Region, and City.

Geolocation is gathered only on app start or resume, so a user's location is based on their most recent session.

We provide methods to disable automatic collection of GPS/Cell-based geolocation (not IP), as well as a method to set user location manually, which allows you to truncate the lat/long to a custom number of decimal points, ultimately limiting the precision of geolocation and protecting user privacy. You could, for example, truncate to 2 decimal places, blurring the accuracy to about 1 kilometer.

Note: If you setup a message or campaign with a geofence region that has a radius smaller than 20km, we only include users with CELL or GPS Location accuracy. (Because this kind of campaign is very location-specific, we require a high degree of confidence to run it.) If the geofence radius is 20km or larger, we will also include users with IP Location accuracy.

To use location-based services in Leanplum, you'll need to include our location framework in your podfile:

pod 'Leanplum-iOS-Location'

Or if you need iBeacons as well, include our Location and Beacons framework instead:

pod 'Leanplum-iOS-LocationAndBeacons'

If you plan to use location-based messaging, you'll need to make some changes to your .plist. See messaging for more info.

Geolocation is available on iOS SDK 1.4+.

Getting permission from users

On iOS, your app must get permission from a user to access their location while using your app. Our SDK automatically asks a user for permission on your behalf. You simply need to import the Location library into your AppDelegate, and add NSLocationWhenInUseUsageDescription to your info.plist file.

#import <LeanplumLocation/LPLocationManager.h>
import LeanplumLocation

You can disable the automatic iOS prompt by setting the authorizeAutomatically property of LPLocationManager to false before calling start.

LPLocationManager * LPLocation = [[LPLocationManager alloc] init];
LPLocation.authorizeAutomatically = NO;
[Leanplum start];
LPLocationManager.shared().authorizeAutomatically = false;

If you've disabled automatic authorization, you can request permission using the authorize method. Optionally, you can check if the user has already given permission with needsAuthorization.

LPLocationManager * LPLocation = [[LPLocationManager alloc] init];
  [LPLocation authorize];
if(LPLocationManager.shared().needsAuthorization) {

iOS will only allow you to request access to a user's location once. After that, the user has to navigate to the privacy settings for your app in the iOS Settings app.

Disabling location collection

If you do not want to send GPS/Cell location to Leanplum, then do not include either of the location frameworks above. Alternatively, you can include the frameworks, but call disableLocationCollection before start.

[Leanplum disableLocationCollection];

disableLocationCollection is available on iOS SDK 1.4.3+.

Manually set user location

Our SDK now allows you to set user location by calling setDeviceLocationWithLatitude before start. You should call disableLocationCollection before setting the user location.

Leanplum.setDeviceLocationWithLatitude(40.748817, longitude: -73.985428)

Setting device location is available on iOS SDK 1.4.3+.