Setting user IDs

Learn how to set user IDs through the Braze SDK. These are unique identifiers that let you track users across devices and platforms, import their data through the user data API, and send targeted messages through the messaging API. If you don’t assign a unique ID to a user, Braze will assign them an anonymous ID instead—however, you won’t be able to use these features until you do.

About anonymous users

After you integrate the Braze SDK, users who launch your app for the first time will be considered “anonymous” until you call the changeUser method and assign them an external_id. Once assigned, you can’t make them anonymous again. However, if they uninstall and reinstall your app, they will become anonymous again until changeUser is called.

If a previously-identified user starts a session on a new device, all of their anonymous activity will automatically sync to their existing profile after you call changeUser on that device using their external_id. This includes any attributes, events, or history collected during the session on the new device.

Setting a user ID

To set a user ID, call the changeUser() method after the user initially log ins. IDs should be unique and follow our naming best practices.

If you’re hashing a unique identifier instead, be sure to normalize the input of your hashing function. For example, when hashing an email address, remove any leading or trailing spaces and account for localization.

• android
• swift
• web
• cordova
• roku
• unity
• unreal engine

1
Braze.getInstance(context).changeUser(YOUR_USER_ID_STRING);

1
Braze.getInstance(context).changeUser(YOUR_USER_ID_STRING)

1
AppDelegate.braze?.changeUser(userId: "YOUR_USER_ID")

1
[AppDelegate.braze changeUser:@"YOUR_USER_ID_STRING"];

1
braze.changeUser(YOUR_USER_ID_STRING);

1
BrazePlugin.changeUser("YOUR_USER_ID");

1
m.Braze.setUserId(YOUR_USER_ID_STRING)

1
AppboyBinding.ChangeUser("YOUR_USER_ID_STRING");

1
UBraze->ChangeUser(TEXT("YOUR_USER_ID_STRING"));

User aliases

How they work

Although anonymous users don’t have external_ids, you can assign them a user alias instead. You should assign a user alias when you want to add other identifiers to the user but don’t know what their external_id is (for example, they aren’t logged in). With user aliases, you also can:

• Use the Braze API to log events and attributes associated with anonymous users
• Use the External User ID is blank segmentation filter to target anonymous users in your messaging

Setting a user alias

A user alias consists of two parts: a name and a label. The name refers to the identifier itself, while the label refers to the type of identifier it belongs to. For example, if you have a user in a third-party customer support platform with the external ID 987654, you can assign them an alias in Braze with the name 987654 and the label support_id, so you can track them across platforms.

• android
• swift
• web
• rest api

1
Braze.getInstance(context).getCurrentUser().addAlias(ALIAS_NAME, ALIAS_LABEL);

1
Braze.getInstance(context).currentUser?.addAlias(ALIAS_NAME, ALIAS_LABEL)

1
Appboy.sharedInstance()?.user.addAlias(ALIAS_NAME, ALIAS_LABEL)

1
 [[Appboy sharedInstance].user addAlias:ALIAS_NAME withLabel:ALIAS_LABEL];

1
braze.getUser().addAlias(ALIAS_NAME, ALIAS_LABEL);

1
2
3
4
{
  "alias_name" : (required, string),
  "alias_label" : (required, string)
}

ID Naming best practices

We recommend that you create user IDs using the Universally Unique Identifier (UUID) standard, meaning they are 128-bit strings that are random and well distributed.

Alternatively, you can hash an existing unique identifier (such as a name or email address) to generate your user IDs instead. If you do so, be sure to implement SDK authentication, so you can prevent user impersonation.

While its essential that you correctly name your user IDs from the start, you can always rename them in the future using the /users/external_ids/rename endpoint.