
Seamless user onboarding with Braze comes down to five Canvas decisions made in a fixed order: the activation event, the entry trigger, the exit rule, the waiting logic and the channel route. Each one maps to a documented Canvas setting, and getting the order right stops the journey messaging a user once they've activated.
Key Takeaways
- Fix the activation event first, because Braze asks you to align exit events with your primary conversion.
- Use a segment for the audience and an event for the trigger, because the same trigger in both can cause a race condition.
- A user who performs the exit event is marked to exit immediately but stays in a Delay step until the delay ends.
- Action Paths hold users for an evaluation window, one day by default and 31 days at most.
- Subscription settings apply per step, so entry and reach need separate checks.
- Users advance through Message steps whether or not they received the message, so add a Decision Split where later logic depends on delivery.
What does seamless user onboarding with Braze involve?
Onboarding is a journey with an end condition, which is why it belongs in Canvas. Braze positions Canvas for guiding users through a multi-step journey, and campaigns for a single messaging step across one or more channels. If your first-week plan has more than one message and any branching, you're building a Canvas.
Seamless means a new user never receives a message that ignores something they've just done. That's a design goal rather than a Braze setting. We recommend making the five decisions below in order, because each one constrains the next.
| Decision | Canvas setting | Documented behaviour to design around |
|---|---|---|
| 1. Activation event | Conversion event and exit criteria | Conversion events power Canvas optimisation and reporting, and exit events should align with the primary conversion. |
| 2. Entry trigger | Entry schedule and Target Audience | Action-based entry starts users when they take particular actions. The audience is evaluated before users enter. |
| 3. Exit rule | Exit criteria exception event | Braze marks the exit immediately, but a user in a Delay step stays there until the delay ends. |
| 4. Waiting logic | Delay and Action Paths | A Delay step can run up to 730 days. An Action Paths evaluation window tops out at 31 days. |
| 5. Channel route | Subscription settings, Audience Paths, in-app messages | Subscription settings apply per step and have no effect on who enters. |
Which activation event should end the onboarding journey?
Choose this first. Braze's launch checklist asks you to set a primary conversion event and to align exit events with that conversion. Your activation event is that conversion, so every later setting depends on it.
Pick an event that already reaches Braze with a stable name and stable properties. Braze's guidance on matching exit criteria to entry events says to verify property names and data types. Entry events must match those used in your exit criteria or Action Paths steps.
Do that check before the build starts, not during launch review. Then set the conversion window. Braze documents that conversions are tracked even after the Canvas ends, while exits aren't tracked once the user exits.
Braze recommends a conversion window that at least matches the longest path in the Canvas. When your exit count and conversion count differ, that's documented behaviour and not a tracking fault.
How should a new user enter the onboarding Canvas?
When onboarding starts with something the user does, action-based entry is the natural fit. Braze describes it as users entering and receiving messages when they take particular actions, such as opening your app or triggering a custom event. We suggest the earliest event that proves the person exists in your product, such as account creation.
Keep the who and the what separate. Braze gives the example of targeting new users with a segment of people who first used your app less than a week ago. Use a segment for the audience and an event for the trigger.
Braze warns against using the same trigger as an audience filter. The documented risk is a race condition: the user may not be in the audience at the moment they perform the trigger event, so they never enter.
If events reach Braze from your own servers rather than the SDK, confirm the custom event timestamp is the current time rather than a backdated one. Braze advises this check if an action-based Canvas sends messages earlier than expected. Then decide re-entry on purpose, because entry controls determine whether users can re-enter.
Braze also lets you limit how many people can enter by a selected cadence. For action-based Canvases that cadence is hourly, daily or the lifetime of the Canvas.
What should the exit rule be?
Exit on the activation event. Braze says to use exit criteria when you want a user to leave the Canvas entirely after an action that matches their entry event. Use Action Paths instead when you want them to stay but follow a different path.
The detail that catches teams out is the Delay step. When a user performs the exit event, Braze marks them to exit immediately and they don't advance to later steps. If they're in a Delay step, they remain there until the delay period ends.
That's why "Total Exits by Exit Criteria" in Canvas analytics only updates after a user has fully exited. We suggest reading the first week of exit data as incomplete and judging the Canvas on conversions.
How long should the Canvas wait between messages?
A Delay step can hold users for up to two years (730 days). Braze's own example is an extended delay before nudging new users who haven't started a session.
Delays measure "days" and "calendar days" differently. A day is 24 hours from the moment the user enters the step. A calendar day waits until the next specified time, which could be less than 24 hours.
Use that difference deliberately. We recommend calendar days at a specific time when a message should land at a recognisable time of day, and days when it should land a full day after the previous step.
For milestone-based onboarding, Action Paths do more work than plain delays. Users are held for an evaluation window, one day by default, with a maximum of 31 days. They advance through the first action group whose trigger they perform.
Anyone who performs none of the triggers falls through the Everyone Else group at the end of the window. We suggest sizing each window to how long a real user needs for that step, and letting the Everyone Else group carry your nudge.
Canvas steps move users only forward in the flow. A repeated reminder therefore has to be drawn as separate steps in sequence. We suggest fewer, better-timed reminders over a long chain, and Braze recommends naming every step as you build.
How do you reach new users on the right channel?
Entry and reach are separate questions. Braze applies subscription settings per step, with no effect on the entry audience. A user can therefore enter a Canvas and still be unreachable on a given channel.
Braze's checklist suggests routing push-enabled users toward push steps and email-subscribed users toward email using Audience Paths. That keeps reporting sizes accurate and avoids sending users down unreachable channels.
Watch the advancement default. Users advance through all Message steps regardless of whether they received the message. If a later branch assumes "the push was delivered", add a Decision Split directly after the Message step to advance only users who received it.
Braze recommends in-app messages for onboarding Canvases, and in-app messages work with action-based entry, though not on classic action-based steps (trigger and delay). One documented quirk affects timing. When the action group trigger is starting a session and the next step is an in-app message, the user must perform two session starts to receive it.
We suggest not building an onboarding branch that expects an in-app message on the very next session. Which users you may message on which channel is a consent question that this post doesn't settle.
What does a hypothetical onboarding decision look like end to end?
Imagine a grocery delivery app. This is an illustration only, with no client data and no invented figures. The team agrees that activation means placing a first order.
The entry is action-based on account creation. A segment of recent first-time users forms the audience, so the trigger and the audience filter are different things. The exit event and the conversion event are both "first order placed", and the conversion window covers the longest path.
The first message goes by email and push, routed with Audience Paths. After it, an Action Paths step holds users for a window sized to a typical first session. One action group covers adding a payment method, and an Everyone Else group takes the rest.
The Everyone Else users receive a single nudge, followed by an extended delay and a final message for people who haven't started a session. Now trace a user who orders during the extended delay. The exit event marks them immediately, so they receive nothing further, and the exit count catches up only when the Delay step ends.
Which checks should run before an onboarding Canvas goes live?
Braze publishes a full Canvas QA checklist. These five items carry the greatest weight for onboarding, in the order we'd run them:
- Verify the triggering datapoint appears on a live user profile in Messaging History.
- Confirm control group size, because you can't add a control group retrospectively.
- Duplicate the Canvas and restrict entry to test users only, filtering on external ID, email address or phone number.
- For action-based journeys, confirm quiet hours won't delay messages that require urgent delivery.
- Add a Decision Split after any Message step whose result a later branch depends on.
How does this connect to the rest of the programme?
Onboarding doesn't stop at the Canvas. For the build itself, see our step-by-step onboarding workflow guide, and for tailoring the journey to each user, see personalised onboarding in Canvas.
Channel-specific detail sits in two further posts: onboarding new mobile users from first open and push notifications for onboarding completion. To judge whether the journey works, read key onboarding metrics in Braze and feedback surveys for onboarding.
As a Braze implementation partner, CustomerIK recommends fixing the activation event before anyone opens the Canvas builder, then making the entry, exit, waiting and channel decisions in that order, and testing exit behaviour on a duplicate with short delays before launch. That order gives your exit rule and conversion window one shared definition of success.
Frequently Asked Questions
1. Should onboarding be a Canvas or a campaign?
Braze says to use a campaign for a single messaging step across one or more channels. Use Canvas when the journey has several steps, delays or branches.
2. Can a Canvas send a user back to an earlier step?
No, because Braze documents that Canvas steps move users only forward in the flow, so a repeated message needs its own step.
3. What happens if a user activates while waiting in a Delay step?
Braze marks them to exit immediately and they don't advance to later steps. They remain in the Delay step until the delay period ends.
4. Do subscription settings change who enters the Canvas?
No, because Braze applies them per step, with no effect on the entry audience, so entry and reach need separate checks.
5. Do in-app messages work with action-based entry?
Yes, in Message steps, but Braze notes they aren't available on classic action-based steps (trigger and delay).
Sources
- Braze, Create a Canvas. Retrieved 05 Nov 2026.
- Braze, Exit criteria. Retrieved 05 Nov 2026.
- Braze, Matching exit criteria to entry events. Retrieved 05 Nov 2026.
- Braze, Canvas QA checklist. Retrieved 05 Nov 2026.
- Braze, Action Paths. Retrieved 05 Nov 2026.
- Braze, Delay. Retrieved 05 Nov 2026.
- Braze, Canvas best practices. Retrieved 05 Nov 2026.
- 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 you're deciding which activation event should end your onboarding Canvas, let's talk.




