.svg)
Onboarding new mobile users with Braze starts before sign-up, because the SDK creates an anonymous profile on first launch. Your journey has to carry across the moment you call changeUser and identify the person. This guide covers what Braze knows in the first session, when to identify, what merges, how to build the Canvas entry audience, and what to test.
Key Takeaways
- A profile exists from first launch, anonymous and device-specific, before anyone signs up.
- Assign an external_id with changeUser once the user is recognisable, and never before you can uniquely identify them.
- A new external_id keeps the anonymous history, while an existing one is worded differently on two Braze pages, so test it.
- Uninstalling and reinstalling creates a new anonymous profile until changeUser is called again.
- Trigger an action-based Canvas on the action and filter on something else, to avoid a race condition.
- Merges can't be undone, and the Messaging History tab isn't updated after one.
How does onboarding new mobile users with Braze start before sign-up?
According to the Braze user profile lifecycle documentation, any user without a designated external_id is called an anonymous user. That includes people who downloaded your mobile app but didn't create a profile. When the SDK first recognises them, Braze creates an anonymous profile.
Its braze_id is assigned automatically, cannot be edited and is device-specific. So your onboarding audience exists from the first launch, before anyone has typed an email address.
You can still reach that audience. The documentation describes an External User ID is blank segmentation filter for targeting anonymous users. It also describes using the API to log events and attributes for them.
What does Braze know about a new user in the first session?
Braze automatically collects certain data when the SDK initialises, as the SDK data collection page describes. Some of it matters for onboarding more than the rest, and one attribute needs a permission your app has to earn.
| Attribute | What the documentation says it is used for | Onboarding use |
|---|---|---|
| Language | Translating messages to a user's preferred language | Welcome copy in the right language from message one |
| Time zone | Sending messages at the appropriate time, according to each user's local time zone | Scheduling the first nudge sensibly |
| Notification settings | Whether this app has push notifications enabled | Deciding whether push can be the next step |
| Last known location | The last known GPS location of the user's device, which requires the user to grant location permission | Only available after the permission prompt is accepted |
In-app messages and Content Cards sync to the device at session start. A first-session welcome therefore depends on the session having started. Session start and session end do count toward your data point usage, unlike the other automatically tracked data.
When should you call changeUser during onboarding?
The documentation suggests assigning an external_id with the changeUser method once the user is recognisable in your app. It also warns against assigning one before you can uniquely identify them. After you identify a user, you can't revert them to anonymous.
We recommend identifying at the moment the account exists, not at install and not at the first screen. Until then the anonymous profile is doing its job, and a premature identifier creates a profile you can't walk back.
Two details are worth knowing before you write the call. Calling changeUser with a different user ID automatically ends the current session and starts a new one. Braze also recommends identifiers built to the Universally Unique Identifier standard, as the setting user IDs page explains, and advises against guessable values and incrementing numbers.
What happens to the anonymous profile when the user signs up?
Two outcomes are described, and they depend on whether the external_id already exists in Braze.
| Scenario | What the documentation describes |
|---|---|
| The external_id is new | The anonymous user becomes a new identified user and retains the same attributes and history |
| The external_id already exists | Braze orphans the anonymous user, merges specific fields that don't exist on the identified profile, and removes the anonymous profile from your user base |
In the second case the lifecycle page lists what carries over. Push tokens and message engagement history are carried over. Custom attributes, custom events and purchase history are merged only when those fields don't already exist on the identified profile.
When data conflicts, the identified user's values are kept. Orphaned users are not eligible to receive messages.
The setting user IDs page words the existing-user case more tightly, saying the anonymous profile's data is not merged. Braze describes this in more than one place, and the emphasis differs. We recommend testing the case on a test profile with your SDK version before you rely on either reading.
The Messaging History tab is powered by a data warehouse and is not updated after a merge. Pre-merge events won't appear there, so plan your onboarding reporting around that.
How should the entry audience for an onboarding Canvas be built?
With action-based delivery, users enter the Canvas when they take a particular action, such as opening your app. Braze evaluates the target audience first, as the Canvas creation page explains. For new users, the documentation suggests a segment of people who first used your app less than a week ago.
One warning from the Canvas documentation applies directly to onboarding. Avoid configuring an action-based Canvas with the same trigger as the audience filter, such as a custom event. A race condition may occur where the user isn't in the audience when they perform the trigger event, so they never enter.
Our suggestion is to trigger on the action and filter on something else, such as the first-use window. Then set exit criteria that match your conversion, because a user who performs the exception event stops receiving messages. Add a control group, since Braze tracks conversions for users placed in it even though they receive no messages.
How would a hypothetical language-learning app onboard a new user?
This section is illustrative. Take a hypothetical language-learning app on iOS and Android, which describes no client, no result and no real data. The sequence is our suggestion, not a documented Braze procedure.
On first launch the app creates an anonymous profile. A welcome in-app message appears at session start, because in-app messages sync then. The user picks a language and starts a first lesson without an account.
Everything they do is logged against the anonymous profile. At the sign-up screen the app calls changeUser with a freshly generated identifier that doesn't exist in Braze yet. The anonymous profile becomes the identified profile with its history intact.
A custom event for account creation then triggers the onboarding Canvas. The Canvas filters on the first-use window, not on that event. It checks whether push is enabled and branches on the answer, which keeps the push-permission conversation off the first screen.
Later, a returning user signs in on a second device with an existing identifier. The team has already tested that case, so it knows what carries over.
What should you check before the onboarding journey goes live?
Run the same routine each time, using internal test profiles before launch:
- Install fresh on a test device and confirm an anonymous profile is created with its own braze_id.
- Call changeUser with a new identifier and confirm attributes and history carry over.
- Repeat with an identifier that already exists, and record exactly what carries over and what doesn't.
- Uninstall and reinstall, and confirm the device returns as a new anonymous profile.
- Walk a test user through entry and exit criteria, and check the trigger is not also the audience filter.
Step four matters because uninstalling and reinstalling an app generates a new anonymous braze_id. Until changeUser is called again, that person is a new anonymous user, and your onboarding Canvas treats them as one.
Which identity mistakes break an onboarding journey?
Failures usually come from a few choices made in the first release. Using one shared default ID, or calling changeUser when a user logs out, is the pattern to avoid. Braze documents both as things not to do.
Delaying SDK initialisation can suit apps that may collect no data before identification, but only the first time a user downloads the app. Delaying it at every sign-out or session start interferes with prefetching in-app message and Content Card assets.
Write the identification rule down before the first release ships. Identity code is written once and rarely revisited, so a wrong choice here follows every later campaign.
Merges can't be undone. The collection best practices page says that after user profiles are merged, this action cannot be undone. If duplicate profiles already sit across several systems, our customer data management service covers identity resolution.
How does this connect to the rest of the programme?
Identity is the foundation for everything after the first session. For the push step, see Braze push notifications for onboarding completion. For the journey itself, read how to automate your onboarding journey using Braze Canvas.
For ideas to test, see 10 onboarding campaigns for better user activation. The trigger events need to be named well, so tracking user events for better campaigns in Braze comes first. Deep links can take a new user to the right screen, as covered in using deep links to drive mobile engagement.
To learn why a new user stalled, read using feedback surveys in Braze to improve onboarding. Our case study on consolidating fragmented customer profiles into one unified profile covers the data side of the same identity problem.
As a Braze implementation partner, CustomerIK recommends treating the moment of identification as a designed step. Decide when it happens and test both the new-ID and existing-ID paths. Write down what your onboarding Canvas assumes about the profile it receives.
Frequently Asked Questions
1. Does Braze create a profile before a user signs up?
It does. Users who launch your app for the first time are anonymous until you call changeUser and assign an external_id. Their profile carries a device-specific braze_id.
2. Can I make an identified user anonymous again?
You can't revert them. After you identify a user, they stay identified. If they uninstall and reinstall your app, they become anonymous again until changeUser is called.
3. Does calling changeUser end the session?
It can. Calling it with a different user ID automatically ends the current session and starts a new one.
4. Can I message people who haven't signed up?
You can. The documentation describes a segmentation filter for users whose external ID is blank. It also describes using the API to log events and attributes for anonymous users.
5. What kind of user ID should I use?
The documentation recommends identifiers built to the Universally Unique Identifier standard, which are random and well distributed. It warns against guessable values and incrementing numbers.
Sources
- Braze, User profile lifecycle. Retrieved 19 Oct 2026.
- Braze, Set user IDs. Retrieved 19 Oct 2026.
- Braze, Create a Canvas. Retrieved 19 Oct 2026.
- Braze, SDK data collection. Retrieved 19 Oct 2026.
- Braze, Collection best practices. Retrieved 19 Oct 2026.
- This post rests on Braze documentation only. Behaviour was read from the pages above on 19 Oct 2026, so check the current pages before you rely on it.
- Written by CustomerIK, a Braze implementation partner.
CustomerIK is a Braze implementation partner working across onboarding, technical integration, marketing operations and customer data management.
If your first-session identity rules are still undecided, let's talk.
.svg)
