.svg)
Braze push notifications help onboarding only when the permission prompt, the trigger and the fallback are designed together. Ask for permission after a first valuable action, use the no-code push primer, branch the journey for people who decline, and exit users the moment they finish.
Key Takeaways
- Ask for push permission at the first moment of real value, inside the flow and not after it.
- Build the primer with the "Request Push Permission" button action, so the SDK checks each device.
- Plan for the no: iOS prompts once per install, and Android 13 and up blocks prompts after two denials.
- Exit users on the completing event, and place the nudge after any Delay step.
- Send people push cannot reach the same nudge by in-app message or email.
- Compare like with like: users who accept a primer are already inclined to finish.
How do Braze push notifications fit into onboarding?
In this post, onboarding completion means a user performs the custom event you have defined as the last onboarding step. Push is a reminder channel for people who started and stalled. It can only reach a device that has granted permission.
Braze puts the stakes plainly. You get one chance to ask users for push permission, and optimising push registration is crucial to the reach of your push messages. Three decisions follow: when to ask, what happens after a no, and what the journey does for people push cannot reach.
When should you ask for push permission during onboarding?
Braze suggests waiting until a user completes some sort of high-value action. That is a sign they are starting to see value in your app. The Android developer documentation says much the same: let people familiarise themselves with the app before you ask for any permission.
Braze guidance for web soft prompts is blunter. Show the prompt after users understand your product value, and not on first page load.
We recommend placing the prompt at the first moment of real value. That moment usually sits inside the flow and not after it. If you wait until onboarding is finished, the people you want to nudge are the ones who stalled, and they never saw the prompt.
If you ask on the first screen, you spend your single chance before the user has a reason to say yes.
How do you build a push primer in Braze?
A push primer is an in-app message that explains what the user will receive. It appears before the operating system shows its own prompt. You can build it without custom code, using the button on-click behaviour "Request Push Permission" on an in-app message for iOS, Android or Web.
The steps below follow the Braze documentation.
- Create an in-app message with a fullscreen or modal layout, so there is room for the copy and both buttons.
- Write copy that is specific about what kind of notifications you will send and what value they give.
- Add two buttons. Braze recommends "Allow notifications" and "Not now" as starters. Set the first to "Request Push Permission" and the second to "Close Message".
- Schedule the message as action-based, with Perform Custom Event as the trigger action, and fire that event at your first-value moment.
- Ask your developers to remove any existing code that requests push permission, so the primer is the first prompt users see.
The button behaviour needs a minimum SDK version on each platform.
| Platform | Minimum SDK version for the button behaviour |
|---|---|
| Swift | 5.4.0 |
| Web | 4.0.3 |
| Android | 21.0.0 |
Targeting is where multi-device households cause trouble. Braze captures data at the profile level and not the device level. A filter such as Push Subscription Status is not Opted In excludes a user who opted in on another device, so their new phone never gets the primer.
The recommended fix is the no-code primer with no extra push status filters, because the SDK checks that specific device. If you build your own logic or deep link instead, the SDK cannot recognise a primer and shows the message to every device. In that case, filter on Foreground Push Enabled For App being false.
If device and profile records disagree across your wider stack, our customer data management service page covers cross-device matching and deduplication.
What happens on each platform when someone says no?
Plan for the no before you design the yes. The operating system enforces the prompt, so the rules differ by platform. Your journey has to cope with each of them.
| Platform and state | Does the primer show? | What the journey should do |
|---|---|---|
| iOS, user has not responded | Yes | Show the primer at the first-value moment. |
| iOS, user denied | No. iOS only allows the native prompt once. | Route to in-app or email, and offer a way to the device settings. |
| Android 13 and up, denied twice | No. Android blocks further prompts. | Same as iOS denied. |
| Android 12 and earlier | Not recommended, because push is opted in by default. | Skip the primer and send push directly. |
| Web, permission denied | No. The state cannot be recovered in the browser. | Use email or in-app only. |
On the web, trigger the primer from a user click. Braze notes that some modern browsers show the prompt only after a user gesture, and a request on page load will likely be ignored or silenced.
On iOS, a device with provisional authorisation still qualifies for the primer, and it receives a foreground push token. If you combine provisional authorisation with a primer, Braze advises contacting your Braze representative for guidance.
If an app's push setting is off, Braze says you need to redirect the user to the push settings in the device settings. A soft prompt on the web matters for the same reason. The browser throttles how often you may prompt directly, and a denial cannot be undone from your side.
How should the onboarding Canvas treat push users and everyone else?
Start with an action-based entry. Braze describes action-based delivery as very effective for achievement-based messages. For onboarding, the entry trigger is your sign-up event.
Then set the exit criteria to the completing event. When a user performs the exit event, Braze marks them to exit immediately, and they do not advance to later steps. Delays have a catch: a user already in a Delay step stays there until the delay ends.
Place the nudge after the delay, and the exit will stop it from sending. Braze also covers matching exit criteria to entry events. That helps when onboarding has several tracks and a user should only leave after finishing the track they entered.
Our suggestion is to add the fallback here. A push step reaches only users who are subscribed or opted in and have foreground push enabled. Braze also says subscription state does not guarantee delivery.
Treat push reachability as a device fact. Send people who cannot receive push the same nudge as an in-app message or an email. Braze notes that other channels can reach users who ignore pushes more effectively, and names in-app messages and email.
What should an onboarding push say?
Braze recommends keeping each line of the title and body to approximately 30-40 characters. It suggests making a push actionable and beneficial in less than 40 characters. Always test on a real device before you send, because the final render of any Liquid personalisation varies from user to user.
Name the step the user left and send them straight back to it. A nudge that says "Finish setting up" is weaker than one that names the next action. Deep links make this possible.
Keep personal details out of the copy. Braze says push should not be used to send sensitive personal or confidential information.
Two policy points sit alongside it. The Braze push best practices page quotes Apple's App Store policy, which says push notifications must not be required for the app to function. The same page quotes a rule against using push for promotions or direct marketing without explicit opt-in consent language in your app.
Whether a given onboarding reminder counts as marketing is a legal question this post does not settle.
What does this look like for a hypothetical app?
Take a hypothetical meal-planning app with three onboarding steps. Users create an account, set household preferences and save a first weekly plan. Saving the plan is the completion event.
The first moment of value is when the user sees a suggested plan, so the primer fires there. Users who accept get a single push nudge after a delay, if the completion event has not happened. The exit criteria remove anyone who saves a plan during the delay.
Users who decline, or whose devices the primer cannot reach, get the same nudge as an in-app message on their next session or as an email. Every user ends up with one nudge on one channel. The push step is never the only way to finish.
This example is illustrative. It uses no client data and describes no real result.
What goes wrong, and how do you catch it?
These are the failures we would check for before launch. Each one has a documented cause.
| Failure | What it looks like | Fix |
|---|---|---|
| The double prompt | The native prompt appears before your primer, so the primer has nothing left to ask. | Remove old permission code so the primer is first. |
| The custom-link primer | A deep link or custom logic stands in for the button, so the message shows on every device. | Use the "Request Push Permission" button action. |
| The user-level filter | Users with a second device never see the primer on the new one. | Drop push status filters, or use the device-level filter. |
| Subscription read as reachability | The audience count looks healthy and the push reaches fewer people. | Check foreground push enabled, not subscription state alone. |
| A short conversion window | Late completions fall outside the window and are not tracked against the Canvas. | Braze recommends setting the conversion window to at least match the longest path in the Canvas. |
A user who declines at the operating system prompt stays Subscribed, and the profile shows no foreground push token. Braze does not automatically change a user's push subscription state to Unsubscribed when they opt out at the operating system level. The profile can say subscribed while the device says no.
Braze suggests letting users control push inside your app. Turning notifications off at the device level removes their foreground push token.
Shared devices need thought too. An app can hold only one push subscription per device, so when a new user logs in, the push token is reassigned to them. Test every step in a development environment before launch, as Braze advises for Canvas configurations.
One measurement trap deserves a name. Users who accept the primer are already inclined to finish. A comparison of completion between accepters and decliners overstates what push did.
Compare like with like. Treat the push step as one part of the journey and not the cause of completion.
How does this connect to the rest of the programme?
Push is one channel in a wider onboarding build. Our overview of 10 proven onboarding campaigns shows where a nudge sits among the other messages. The walkthrough on automating an onboarding journey with Canvas covers entry and exit setup in more depth.
The completing event and the first-value event both depend on tracking user events properly. The primer itself is an in-app message, so our guide to in-app message triggers applies directly.
Once users have opted in, push notification segmentation keeps later messages relevant. Deep links take each nudge to the right step.
As a Braze implementation partner, CustomerIK recommends treating push permission as a product moment and not a technical setting. Agree the first-value event with the product team. Build the no-code primer on it, and give every user who cannot receive push an equivalent nudge on another channel.
Frequently Asked Questions
1. Should I ask for push permission on first launch?
Braze suggests waiting for a high-value action. The Android developer documentation advises letting users familiarise themselves with the app first. Asking on first launch spends your one chance before the user has a reason to agree.
2. Can I show the primer again after someone denies on iOS?
Not through the primer. The Braze documentation says iOS does not show the native prompt again for that app install. The SDK suppresses the primer for denied devices, so the route back is the device settings.
3. Does the primer apply to Android 12 and earlier?
Braze does not recommend it, because push is opted in by default on those versions. Android 13 and up requires permission before push can be shown.
4. Is push subscription state the same as being able to receive push?
They differ. Braze says subscription state does not guarantee delivery, because a user also needs foreground push enabled on a device. Check both when you build the audience.
5. How long should an onboarding push be?
Braze recommends approximately 30-40 characters per line of title and body. It also suggests keeping a push actionable in less than 40 characters.
Sources
- Braze, Push primer in-app messages. Retrieved 14 Oct 2026.
- Braze, Soft push prompts for Web. Retrieved 14 Oct 2026.
- Braze, Push best practices. Retrieved 14 Oct 2026.
- Braze, Push enablement and push subscription. Retrieved 14 Oct 2026.
- Braze, Exit criteria. Retrieved 14 Oct 2026.
- Braze, Matching exit criteria to entry events. Retrieved 14 Oct 2026.
- Braze, Delivery and entry types. Retrieved 14 Oct 2026.
- Android Developers, Notification runtime permission. Retrieved 14 Oct 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 your onboarding journey has a permission moment you have not designed yet, let's talk.
.svg)
