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 LAB course on Mapping User Lifecycles instead.
All persistent data associated with a user will be stored against a user profile.
Once a user profile is created, either after a user is 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:
- 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.
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. The purpose of this is to recognize the same user across multiple devices to a single user profile.
More benefits of user IDs include:
- Provide a consistent user experience across multiple devices and platforms (e.g. 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 ensuring 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 our RESTful User API, and target users with transactional messages using our RESTful Messaging API.
- Search for individual users using our “Testing” filters within the segmenter, and on the User Search page.
Do not assign an
external_id to a user profile before you are able to uniquely identify them. Once you identify a user, you cannot revert them to anonymous.
external_id will merge any relevant user profile data from the anonymous user profile with the existing identified user profile data and 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. These orphaned users are not considered in your user counts and will not be messaged.
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.
external_id is unchangeable once it has been set against a user profile. Any attempt to set a different
external_id during a user’s session will create a new user profile with the new
external_id associated with it. No data will be passed between the two profiles.
To allow referring to users by multiple other identifiers rather than only the Braze
external_id, you can also set user aliases against a user profile. Any alias set against a user profile will act in addition to the user’s
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 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.
external_id, an alias can be updated with a new name for a given label once set. You can do so either via the New User Alias Endpoint, or if you pass 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. 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 an Amplitude ID and a different BI tool ID that you wish to reference within Braze.
Advanced Use Case Information
You can set a new user alias for existing identified user profiles via the SDK and the API. User aliases cannot be set via the API on an unknown user profile.
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.
Uninstalling and reinstalling an app will cause a new anonymous user ID to be generated for that user.
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.
Braze will ban or block users (“dummy users”) with over 5 million sessions and no longer ingest their SDK events because they are usually the result of misintegration. If you find that this has happened to a legitimate user, please reach out to your Braze account manager.