User Profile Lifecycle

All persistent data associated with a user will be stored against a user profile.

Once a user profile is created, either following a user being recognized by the SDK or created via API, there are a number of identifiers that can be assigned to a profile to identify or reference that user. These are the:

• braze_id
• external_ id
• Any number of aliases that you choose to set for your user base

Anonymous User Profiles

Initially, when a user profile is recognized via the SDK an ‘anonymous’ user profile is created with an associated braze_id: a unique user identifier that is set by Braze. This identifier can be used to delete users through the REST API.

The braze_id is automatically assigned by Braze, cannot be edited and will be device-specific.

Identified User Profiles

Once a user is recognizable in your app (by providing a form of user ID or email address) we suggest assigning an external_id to that user’s profile. The purpose of this is to recognize the same user across multiple devices to a single user profile.

Setting an external_id will merge any relevant user profile data from the anonymous user profile with the existing identified user profile data and orphan/remove the remaining, irrelevant parts of the previously anonymous profile data from our database. This method can prevent an orphaned user from receiving a campaign that has already been received or opened by your identified user or prevent various errors that can occur when there are duplicates of your users in Braze.

On the first instance of assigning an external_id to an unknown user profile all, existing user profile data will be migrated to the new user profile.

For further information on how to set an external_id against a user profile please see our documentation (iOS, Android, Web).

User Aliases

To allow for customers to refer to users by multiple other identifiers, rather than only the Braze external_id, clients can also set user aliases against a user profile. Any alias set against a user profile will act in addition to the user’s braze_id or external_id as opposed to replacing it. There is not a limit as to the number of aliases that you can set against a user profile.

Each alias consists of two parts: a label, which defines the key of the alias, and a name, which defines the value. An alias name for any single label must be unique across the user base. If you attempt to update a second user profile with a pre-existing label and name combination the user profile will not be updated.

Unlike an external_id, once an alias is set for a user this can be updated with a new name for a given label. This is possible either via the New User Alias endpoint or if you pass a new name via the SDK. Upon setting a user alias these will be visible when exporting that user’s data.

User aliases also allow customers to tag anonymous users with an identifier. These users can then be exported using their aliases (e.g. for Currents) or referenced by the API.

If an anonymous user profile with an alias is later recognized with an external_id, they will be treated as a normal identified user profile but will retain and can be referenced by their existing alias.

A user alias can also be set on a known user profile to reference a known user by another externally known ID eg. a user may have an Amplitude ID and a different BI tool ID that you wish to reference within Braze.

For information on how to set a user alias please see our documentation for each platform.

Advanced Use Case Information

For existing identified user profiles you are able to set a new user alias via the SDK and the API. User aliases cannot be set via the API on an unknown user profile. For more information on how to reference a user via the API please refer to our documentation.

If you attempt to set a pre-existing external_id on an anonymous user profile which share a matching alias name but with different labels, only the alias label on the pre-existing known user profile will be maintained.

How to Troubleshoot with Braze’s IDs

Aside from acting as a mechanism to organize user data and reference user profiles, all braze_id’s can be used to find and identify users within your dashboard for testing. To find your user in the Braze dashboard please see our Adding Test Users section.