Show an in-app before the push permission prompt

A pre-permission in-app is a message you show before the system push permission prompt. Use it to explain why push notifications are useful, then ask for permission only after the user says yes in your in-app.

On iOS, the system prompt appears only once per install. If the user taps Don’t Allow, the app can’t show that prompt again. Push stays off until they turn notifications on in Settings. Asking in-app first means you spend that one shot only on users who’ve already said yes to you.

Use this guide if you want to design one cross-platform HTML prompt in the Control Panel and trigger it by event on both iOS and Android.

Use a different guide if:

• Your team will ship an iOS-only prompt in app code (not editable in the Control Panel, not started by a Journey event): iOS push primer.
• You need to re-engage users who already disabled push or never granted it (recovery only, not the first ask): Create opt-out recovery popups.

Before you start

Developer assistance needed

You build the template in the Control Panel. Share the events guide and postEvent with your development team — they handle the two prerequisites below.

Pushwoosh never shows the system permission dialog by itself. There is nothing to configure in the Control Panel to delay it. The dialog appears only when the user taps the accept button in your in-app.

Work with your development team on these prerequisites:

1. Confirm the app does not request push permission earlier (including on first launch).
2. Agree on a custom event name and when to fire it, for example onboarding_completed right after onboarding, or locked_feature_tapped when the user taps a feature that needs notifications. Your team will call postEvent with that name. Learn more about events.

Build the in-app

The buttons in this guide run on custom JavaScript, which only works in an HTML-based in-app template. A native in-app template can’t run this code, so don’t build the template with Native in-app.

1. Go to Content → In-Apps and click Create in-app to open the built-in editor directly.
2. Enter a template name.
3. Open the Blocks tab in the right panel and add a text or heading block with your pitch for enabling push.

4. Add a button block for the accept action and another for the decline action. Both buttons can run their JavaScript as soon as the in-app loads, with nothing else to wait for.

Tip

To set the accept button apart as the primary action, like in the screenshot above, select the decline button, turn on Background in its Styles panel, and set it to transparent. Turn on Text color too and pick a color that still reads clearly against the template’s background.

5. Select the accept button and set Action type to Custom Javascript.
6. Paste only the code below into onClick.

pushwoosh.registerForPushNotifications();
pushwoosh.closeInApp();

7. Select the decline button and set Action type to Custom Javascript.
8. Paste only this into onClick:

pushwoosh.closeInApp();

After you save the template:

• Accept button: the system permission dialog appears.
• Decline button: the in-app closes and no system dialog appears.

A pre-permission in-app shown before the system prompt

Tip

For ZIP / developer upload only: if you build a raw HTML file for ZIP upload, use the full tags there instead of the editor onClick field:

<button onclick="pushwoosh.registerForPushNotifications(); pushwoosh.closeInApp();">Enable notifications</button>
<button onclick="pushwoosh.closeInApp();">Not now</button>

Skip the prompt for users who already opted in

Add a display condition so the in-app hides itself for users who already granted push, even if a later trigger shows the template again. Push consent status comes from Push Alerts Enabled, a default Boolean tag the SDK sets from the device’s system notification permission.

1. In the Layers panel, click the first block, then Shift-click every other block to select the whole template together.
2. Turn on Show this block conditionally. The rule you set below applies to the whole selection at once.
3. Set the rule to Push Alerts Enabled is false.
4. Under If value is unknown, choose Show block. A fresh install with no tag value yet should still see the prompt.

Caution

Push Alerts Enabled updates on the device’s next app open, not the moment the user flips the permission toggle in system Settings. A user who enables push from Settings can still see this block once more until they reopen the app.

Trigger the in-app before permission is requested

A device that hasn’t gone through registration yet has no push token, so you can’t reach it with a push notification. Trigger the in-app by the custom event you agreed on with development.

1. Ask your development team to call postEvent with the agreed event name at the moment you want to ask.
2. Go to Customer Journey Builder → Create Campaign and start with a Trigger-based entry that listens for that event.
3. Add an In-app element and select the template you built. Learn more about sending in-apps via Customer Journey.
4. Launch the journey when you’re ready to show the prompt.

Note

The in-app doesn’t appear the instant the event fires. Delivery happens on the device’s next app open after that.

Example scenario: ask for push permission right after onboarding

Imagine you want to ask for push permission the moment a user finishes onboarding, instead of interrupting the tutorial itself.

1. Create the event onboarding_completed and confirm your development team fires it when the user finishes the onboarding flow. Learn more about creating events
2. Set onboarding_completed as the trigger for your journey, using a Trigger-based entry.
3. Add an In-app element and select the pre-permission template you built.
4. Launch the journey.

Every user who completes onboarding sees the prompt once. The display condition from Skip the prompt for users who already opted in keeps it from firing again for users who already granted push.

Check it worked

The system prompt is one-shot, so testing both buttons takes two test devices (or two fresh installs) that haven’t granted or denied push yet, one for each button. On each device:

1. Fire the agreed event from the app.
2. Reopen the app and confirm the journey delivers your in-app.

Then:

3. On the first device, tap the accept button and confirm the system permission dialog appears.
4. On the second device, tap the decline button and confirm the in-app closes with no system dialog.
5. After the next app open, confirm Push Alerts Enabled matches the permission state on each device.

Build a segment of users who still have push disabled

Filter on Push Alerts Enabled to find users who declined or never granted the permission. The tag is false when push isn’t allowed yet, including before the user has seen the system dialog, so a pre-permission device already falls into this segment.

1. In the segment builder, add a filter by the Push Alerts Enabled tag.
2. Set the operator to is false. Learn more about building segments by tags.

Use this segment to hold back a repeat prompt from users who still don’t have push enabled, or to run a periodic win-back journey. See the opt-out recovery segment for a worked example with the same tag.

See also

• iOS push primer: the native, iOS-only alternative to this cross-platform HTML approach.
• Create opt-out recovery popups: recover users who already disabled push (not the first ask), using the same Push Alerts Enabled tag.
• Create in-apps with JavaScript: the full JavaScript bridge reference.