Collection best practices
Knowing when and how to collect user data for known and unknown users can be challenging when envisioning the user profile lifecycle of your customers. The following article will help clarify different methods and best practices for collecting new and existing user data.
Overview
The following example comprises an email collection use case, but the logic applies to many different data collection scenarios. In this example, we assume you have already integrated a sign-up form or way to collect user information.
Once a user provides information for you to log, we recommend you verify if the data already exists in your database and create a user alias profile or update the existing user profile, as necessary.
If an unknown user were to view your site and then, at a later date, create an account or identify themselves via email sign-up, profile merging must be handled carefully. Based on the method in which you merge, alias-only user information or anonymous data may be overwritten.
Capturing user data through a web form
Step 1: Check if the user exists
When a user enters content through a web form, check if a user with that email already exists within your database. This can be done in one of two ways:
- Check internal database (recommended)
If you have an external record or database containing the provided user information that exists outside of Braze, reference this at the time of email submission or account creation to ensure the information has not already been captured. /users/export/id
endpoint
Run the following call and check to see if the returned users array is empty or contains a value:1 2 3 4
--data-raw '{ "email_address": "[email protected]", "fields_to_export": ["external_id", "user_aliases"] }'
It is not recommended to heavily leverage this endpoint when querying a single user. We apply a rate limit of 2,500 requests per minute to this endpoint. For more information on endpoint rate limits, refer to Rate limits by request type.
Step 2: Log or update user
- If a user exists:
- Do not create a new profile.
- Log a custom attribute (for example,
newsletter_subscribed: true
) on the user’s profile to indicate that the user has submitted their email via newsletter subscription. If multiple user profiles in Braze exist with the same email address, all profiles will be exported.
- If a user does not exist:
- Create an alias-only profile via
/users/track
endpoint. This endpoint will accept auser_alias
object and create an alias-only profile whenupdate_existing_only
is set tofalse
. Set the user’s email as the user alias to reference that user in the future (as the user won’t have anexternal_id
).
- Create an alias-only profile via
Capturing user emails through an email capture form
Using an email capture form, you can prompt users to submit their email address, which will be added to their user profile. For more information on how to set up this form, check out Email capture form.
Identifying alias-only users
When identifying users upon account creation, alias-only users can be identified and assigned an external ID through the /users/identify
endpoint by merging the alias-only user with the known profile.
To check if a user is alias-only, check if the user exists within your database.
- If an external record exists, you can call the
/users/identify/
endpoint. - If the
/users/export/id
endpoint returns anexternal_id
, you can call the/users/identify/
endpoint. - If the endpoint returns nothing, a
/users/identify/
call should not be made.
Capturing user data when alias-only user information is already present
When a user creates an account or identifies themselves via email sign-up, you can merge the profiles. For a list of fields that can be merged, refer to Merge updates behavior.
Merging duplicate user profiles
As your user data grows, you can merge duplicate user profiles from the Braze dashboard. These duplicate profiles must be found using the same search query. For more information on how to duplicate user profiles, check out Merge profiles.
You can also use the Merge users endpoint to merge one user profile into another.
Note that after user profiles are merged, this action cannot be undone.
Additional resources
- Check out our article on the Braze user profile lifecycle for additional context.
- Documentation on setting user IDs and calling the
changeUser()
method for Android, iOS, and Web.