When Leanplum starts for the first time, a new user profile gets created, the UserID value is being set identical to the DeviceID value and Leanplum starts tracking the user sessions for this user.
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 the hash of the MAC address, and in development mode, we use the advertising identifier. On Android, by default, we use the MD5 hash of the MAC address if android.permission.ACCESS_WIFI_STATE is set. Otherwise, we use the ANDROID_ID. See our docs under Users and Devices.
Now here comes the part you have to keep in mind when developing the user flow logic of your app - For the FIRST TIME only a ‘setUserID(“NewCustomUserID”)’ is being called, the ‘NewCustomUserID’ string passed as UserID is going to replace the existing UserID value in the User Profile (which was previously identical to the DeviceID, now it will be ‘NewCustomUserID’). The user profile will have all the previously tracked data.
Now on, EVERY TIME setUserID is being called passing ANOTHER string value, a NEW user profile will be created, the current User session will be closed and another session will be opened for the new User passed as a String. If the new UserId doesn’t exist, a NEW User Profile will be created. You could also pass a custom UserID value as parte of the Leanplum.start() parameters - also in this case calling after another setUserID and passing a different value, will start logging sessions for the new User (creating a new User Profile if it doesn’t exist).
Basically, ‘setUserId’ is going to be used only in a User Login scenario, reflecting the use case where a new user is installing the app for the first time and starts playing around with it - then is logging in (if your app implements any Login logic) and you want to pass a specific value to identify that User having logged in. Calling ‘setUserId’ again, passing a different string value, means that another User has logged in - the previous session is closed and a new session is opened for the latest User being passed in the setUserId parameter.
A very important thing to remember is NOT to do any setUserId for representing a LOGOUT scenario. In that case we suggest to use a setUserAttribute flag to indicate that the User is logged out. Leanplum will be always be in execution and being tracking sessions for the last User who has been passed in a ‘setUserId’.
Let’s look at a sample code. You can get it from here:
- Android : Click here
- iOS: Click here
When the example is run for the first time, the DeviceID value taken by default is going to be also the value used for the User Profile UserID when creating a new User Profile.
The DeviceID can be customized, but Leanplum.setDeviceID has to be run before Leanplum.start() - also beware that a DeviceID can be set only when starting the app for the first time and from a new installation, otherwise it would do nothing (i.e. you cannot change the DeviceID value if the app is already installed and run at least once).
1) Fill App keys in the sample and start the app. Check the Leanplum Dashboard.
Result: Assuming this is the first time you run the sample, you will notice a new User Profile is created and the UserID si set identical by default to the on the DeviceID value:
2) On the Device, fill in some text representing a new UserID being used for logging in and click on the login button.
What is being done in the code once the Login button is clicked is getting the String value and passing it inside 'setUserID' method:
Check Dashboard and console log.
Assuming this was the first time and the User Profile was created first time in bullet #1, you will notice that the new UserID is being merged in the existing User Profile, taking place of the latest UserID value (identical to the deviceID). All the user data collected before the login are maintained.
Basically, so far we described the scenario of a new user installing the app for the first time, playing around with it and then she decides to login specifying a UserID. We store all the collected data so far and change the UserID from the DeviceID value to the newly passed UserID value
3) Click on Logout button.
Result: the current activity is closed but we don't pass any specific UserID value for representing the logout user action. Leanplum will always be in execution and tracking data for the last User who has been passed in the SetUserID. We can use a userAttribute to flag that the User is logged off, in case needed for sorting those users out or for segments.
4) Then click on the Login button again passing another UserID value.
Check Dashboard and console log.
This time a new User Profile is going to be created.
We already logged in with another user before, so in this case the session for the previous user is going to be closed and a new User Profile is going to be created with the new UserID passed in the new login. The previous User session is closed and new session is started for the new User.
This reflects the case of a New User who is logging in into the same device, therefore what we want to happen is to track everything that follows as a new user, separate from the first one who launched the app first time and then logged in.
Also note the results when searching now for one of the UserIDs or for the DeviceIDs. In case of searching for a specific userID, only that User is going to be found in the results:
However, searching for the DeviceID being used for those cases, all the User profiles including that DeviceID are going to be displayed: