User profile lifecycle

This article describes the Braze user profile lifecycle and the various ways to identify and reference a user profile. 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. After a user profile is created, either through the API or after a user is recognized by the SDK, you can assign a number of parameters 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 visited your website but didn’t sign up, or users who downloaded your mobile app but didn’t create a profile.

Initially, when a user is recognized by the SDK, an anonymous user profile is created with an associated braze_id: a unique identifier that is automatically assigned by Braze, cannot be edited, and is device-specific. This identifier can be used to update the user profile through the API.

Identified user profiles

After 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 iPhone app).
• 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 Search Users page.

What happens when you identify anonymous users

One of two scenarios can occur when you identify anonymous users:

1) An anonymous user becomes a new identified user:
If the external_id doesn’t yet exist in Braze, the anonymous user becomes a new identified user and retains all 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 through another device (like a tablet) or imported user data.

In other words, 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 both the anonymous user and known user have a first name, the first name of the known user is maintained. If the known user has a null value and the anonymous user has a value, the anonymous user’s value is merged into the known user’s profile if the value 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 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 your user base (just like with external_id). If you try to update a second user profile with a pre-existing label and name combination, the user profile won’t be updated.

Updating user aliases

Unlike an external_id, an alias can be updated with a new name for a given label after it’s set either by using our User Data endpoints or passing a new name through the SDK. The user alias will then be visible when exporting that user’s data.

Tagging anonymous users

User aliases also allow you to tag anonymous users with an identifier. For example, if a user provides your ecommerce 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.

Behavior of aliases on anonymous user profiles

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.

Setting aliases on known user profiles

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

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

The user aliases are also merged in the process. However, if both the user to be orphaned and the target user have an alias with the same label, only the alias from the target user is maintained.

Uninstalling and reinstalling an app will generate a new anonymous braze_id for that user.

Troubleshooting 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.