This page references our older Objective-C SDK. Check out our new Swift SDK to integrate our latest Swift-first library.
Setting user IDs for iOS
User IDs should be set for each of your users. These should be unchanging and accessible when a user opens the app. Naming your User IDs correctly from the start is one of the most crucial steps when setting up User IDs. We strongly suggest using the Braze standard of UUIDs/GUIDs (detailed below). We also, strongly recommend providing this identifier as it will allow you to:
- Track your users across devices and platforms, improving the quality of your behavioral and demographic data.
- Import data about your users using our user data API.
- Target specific users with our messaging API for both general and transactional messages.
If such an identifier is not available, Braze will assign a unique identifier to your users, but you will lack the capabilities listed for user IDs. You should avoid setting User IDs for users for whom you lack a unique identifier that is tied to them as an individual. Passing a device identifier offers no benefit versus the automatic anonymous user tracking Braze offers by default.
These User IDs should be private and not easily obtained (e.g., not a plain email address or username).
For additional security, we recommend adding our SDK authentication feature to prevent user impersonation.
Suggested user ID naming convention
At Braze, we strongly suggest naming User IDs also known as
external_user_ids, in a UUIDs/GUIDs format. UUIDs/GUIDs are Universally Unique Identifiers that consist of a 128-bit number used to identify information in computer systems. This means that these UUIDs are long, random and well distributed. If you choose a different method in which to name your User IDs, they must also be long, random and well distributed. It is also important to note, that User IDs are case sensitive. For example, “Abcdef” is a different user from “abcdef”.
If you find your
external_user_ids include names, email addresses, timestamps, or incrementors we strongly suggest picking up a new naming method that is more secure. We do not want names, email address, timestamps or incrementors included in your User IDs, because while it might be easy for people within your organization to quickly identify others, it is not a secure method.
Providing this information to others may allow people outside your organization to glean information on how your User IDs are structured, opening up your organization to potentially malicious updates or removal of information. Choosing the correct naming convention from the start is one of the most important steps in setting up User IDs, however a migration is possible using our external ID migration API endpoint.
|User ID Naming|
|Good Example||Bad Example|
Assigning a user ID
You should make the following call as soon as the user is identified (generally after logging in) to set the user ID:
1 [[Appboy sharedInstance] changeUser:@"YOUR_USER_ID_STRING"];
Do not call
changeUser() when a user logs out.
changeUser() should only be called when the user logs into the application. Setting [
changeUser()] to a static default value will associate ALL user activity with that default “user” until the user logs in again.
Be sure to call this method in your application’s main thread. Calling the method asynchronously can lead to undefined behavior.
Additionally, we recommend against changing the user ID when a user logs out, as it makes you unable to target the previously logged-in user with reengagement campaigns. If you anticipate multiple users on the same device but only want to target one of them when your app is in a logged-out state, we recommend separately keeping track of the user ID you want to target while logged out and switching back to that user ID as part of your app’s logout process.
User ID integration best practices and notes
Automatic preservation of anonymous user history
|Identification Context||Preservation Behavior|
|User has not been previously identified||Anonymous history is merged with user profile upon identification|
|User has been previously identified in-app or via API||Anonymous history is not merged with user profile upon identification|
Additional notes and best practices
Please note the following:
- If your app is used by multiple people, you can assign each user a unique identifier to track them.
- Once a user ID has been set, you cannot revert that user to an anonymous profile
- Do Not change the user ID upon a user “log out”.
- Doing so separates the device from the user profile. You will be unable to target the previously logged out user with re-engagement messages. If you anticipate multiple users on the same device, but only want to target one of them when your app is in a logged-out state, we recommend separately keeping track of the user ID you want to target while logged out and switching back to that user ID as part of your app’s logout process. By default, only the last user that was logged in will receive push notifications from your app.
- Switching from one identified user to another is a relatively costly operation.
- When you request the user switch, the current session for the previous user is automatically closed and a new session is started. Furthermore, Braze will automatically make a data refresh request for the News Feed, in-app messages, and other Braze resources for the new user.
If you opt to use a hash of a unique identifier as your user ID take care to ensure that you’re normalizing the input to your hashing function. For example, if you’re going to use a hash of an email address, ensure that you’re stripping leading and trailing whitespace from the input, and taking localization into account.
A user alias serves as an alternative unique user identifier. Use aliases to identify users along different dimensions than your core user ID:
- Set a consistent identifier for analytics that will follow a given user both before and after they have logged in to a mobile app or website.
- Add the identifiers used by a third-party vendor to your Braze users in order to more easily reconcile your data externally.
Each alias consists of two parts: a name for the identifier itself, and a label indicating the type of alias. Users can have multiple aliases with different labels, but only one name per label.
1 [[Appboy sharedInstance].user addAlias:ALIAS_NAME withLabel:ALIAS_LABEL];
1 Appboy.sharedInstance()?.user.addAlias(ALIAS_NAME, ALIAS_LABEL)