User profile lifecycle

This article describes the user profile lifecycle in Braze, and the various ways a user profile can be identified and referenced. If you’re looking to better understand your customer lifecycle, check out our Braze Learning course on Mapping User Lifecycles instead.

All persistent data associated with a user is stored in their user profile.

Once a user profile is created, either after a user is recognized by the SDK or created via the API, there are a number of parameters that can be assigned to that profile to identify and reference that user.

These parameters include:

• braze_id
• external_id
• Any number of custom user aliases that you set

Anonymous user profiles

Any user without a designated external_id is called an anonymous user. For example, these could be users who have visited your website but not signed up or downloaded your mobile app but not created a profile.

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

The braze_id is automatically assigned by Braze, cannot be edited, and is 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 using the changeUser method (web, iOS, Android). An external_id allows you to identify the same user profile across multiple devices.

Additional benefits of using an external_id include the following:

• Provide a consistent user experience across multiple devices and platforms (for example, not sending lapsing user notifications to a user’s Android tablet when they are a loyal user of the app on the iPhone).
• Improve the accuracy of your analytics by confirming users aren’t creating a new user profile every time they uninstall and reinstall, or install the app on a different device.
• Enable import of user data from sources outside the app using the User Data endpoints and target users with transactional messages using our Messaging endpoints.
• Search for individual users using our “Testing” filters within the segmenter, and on the User Search page.

There are two scenarios that occur when you identify anonymous users:

1) An anonymous user becomes a new identified user:
If the external_id does not yet exist in Braze, the anonymous user becomes a new identified user and retains all of the same attributes and history of the anonymous user.

2) An anonymous user is identified as an already existing user:
If the external_id already exists in Braze, then this user was previously identified as a user in the system in some other way, such as via another device like a tablet or through imported user data.

As such, you already have a user profile for this user. In this instance, Braze will do the following:

1. Orphan the anonymous user
2. Merge specific user profile fields that don’t already exist on the identified user profile from the anonymous profile
3. Remove the anonymous profile from your user base so the user counts aren’t inflated

If an anonymous user has a first name and the known user also has a first name set, the first name of the target is maintained. If the target user has a null value, and the anonymous user has a value, it’s merged into the target user if it falls under these specific user profile fields.

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

User aliases

To refer to users by identifiers other than only the Braze external_id, 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’s no limit to the number of aliases that you can set against a user profile.

Each alias functions as a key-value pair that consists of two parts: an alias_label, which defines the key of the alias, and an alias_name, which defines the value. An alias_name for any single label must be unique across the user base (just like with external_id). 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, an alias can be updated with a new name for a given label after it is set either via our User Data endpoints or by passing a new name via the SDK. The user alias will then be visible when exporting that user’s data.

User aliases also allow you to tag anonymous users with an identifier. For example, if a user provides your e-commerce site with their email address but hasn’t yet signed up, the email address can be used as an alias for that anonymous user. These users can then be exported using their aliases 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 their existing alias and can still be referenced by that alias.

A user alias can also be set on a known user profile to reference a known user by another externally known ID. For example, a user may have a business intelligence tool ID (like an Amplitude ID) that you wish to reference within Braze.

For information on how to set a user alias, see our documentation for each platform (iOS, Android, Web).

Advanced use case information

You can set a new user alias for existing identified user profiles via our SDK and our API using the User Data endpoints. However, user aliases can’t be set via the API for an existing unknown user profile.

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

Uninstalling and reinstalling an app will cause a new anonymous braze_id to be generated for that user.

How to troubleshoot with user IDs

All user IDs can be used to find and identify users within your dashboard for testing. To find your user in the Braze dashboard, refer to Adding Test Users.