Skip to main content
This page is part of Example app: a full OneSignal integration, which follows one real app from end to end. The app is Clean Beans, a cleaning rota for shared homes, built with Expo (React Native) and a Supabase backend. In-app messages appear while someone is using the app. Their content, audience, and schedule live in the OneSignal dashboard, so they can change without a release. Clean Beans uses them for five jobs.

Triggers: let the app decide the moment

A trigger is a key and a value that the app sets. Any in-app message configured to match it is shown. Every Clean Beans screen has a help button in its header that sets one trigger, with the screen’s name as the value.
src/components/HelpButton.tsx
app/(tabs)/_layout.tsx
One trigger key serves thirteen screens. Adding help for a new screen means adding a button with a new value and creating a message in the dashboard.
A help overlay in-app message shown over the dashboard

Tapping the help button on the dashboard shows a help overlay.

Dashboard setup. In Messages > In-App, create a message whose trigger is help_topic is dashboard, and repeat for each screen. Multi-step walkthroughs use the same trigger with a carousel layout.
A walkthrough in-app message made of swipeable cards

A multi-step walkthrough built as a carousel of cards.

Custom HTML messages

The help overlays are written in HTML, so they match the app’s design exactly. An HTML in-app message talks to the SDK through the OneSignalIamApi object. Two rules apply to every clickable element:
  • Give it a unique data-onesignal-unique-label, so clicks are tracked correctly.
  • Attach a listener that calls an OneSignalIamApi method. Plain links are not tracked.
docs/iam-html/help-dashboard.html

Push permission pre-prompt

The system permission dialog can only be shown once. An in-app message shown first can explain what the user will get, and only people who tap Enable notifications see the system dialog.
An in-app message explaining the benefits of enabling notifications

A pre-prompt explains the benefit before the system dialog appears.

docs/iam-html/push-permission-prompt.html
If you use a pre-prompt, remove the requestPermission() call from app startup. Otherwise the system dialog appears first and the pre-prompt has nothing left to ask.

App update prompt

When a new version ships, people on the old one see a prompt to update. This message needs no code in the app at all. Its audience is a segment of users on an older app version.
An in-app message asking the user to update the app

The update prompt, shown only to people on an older version.

One message serves both platforms. The script picks the store from the device, and openUrl tracks the click, opens the store, and closes the message.
docs/iam-html/app-update-prompt.html
The greeting uses a tag, with a fallback for users who do not have one.
docs/iam-html/app-update-prompt.html
Dashboard setup. Create a segment with the filter App version less than your current version, and use it as the message’s audience. Update the filter each time you release.
Tag substitution works in the text and attributes of an HTML in-app message, but not inside script tags.

Review prompt: hand a click back to the app

A good moment to ask for an app store rating is right after something went well. Clean Beans asks when a cleaning session takes a streak to a multiple of seven days. This is the one in-app message where a tap has to run code in the app, because the native rating sheet can only be opened by the app itself.
1

The app sets a trigger at a streak milestone

It waits until the session screen has closed, so the prompt never interrupts cleaning, and it remembers the last milestone it asked at.
src/lib/reviewPrompt.ts
2

The message sends a click name back to the app

addClickName passes a name to the app’s click listener. It does not close the message, so the script closes it afterwards.
docs/iam-html/review-prompt.html
3

The app opens the native rating sheet

The click listener checks the name and asks the system to show the sheet.
src/lib/reviewPrompt.ts
app/_layout.tsx
A review prompt in-app message

The in-app message review prompt.

Dashboard setup. Create an HTML in-app message with the trigger ask_for_review is show. Schedule it to show at most once every 17 weeks.
Apple shows its rating sheet at most three times per user in a year, and Google has its own limit, so a tap on the button is not guaranteed to show anything. The sheet never appears in TestFlight builds. Test this flow with an App Store build.

In-app triggers

Trigger types and how they combine.

HTML in-app messages

Design messages with your own HTML.

In-app JavaScript API

Every OneSignalIamApi method.