> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Example app: in-app messages

> How the Clean Beans example app uses in-app message triggers and custom HTML for help overlays, a permission pre-prompt, and update and review prompts.

This page is part of [Example app: a full OneSignal integration](https://documentation.onesignal.com/docs/en/example-full-integration-overview.md), 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.

| Message | Shown when | How it is targeted |
| - | - | - |
| Help overlays | The user taps the help button on a screen | A trigger set by the app |
| Walkthroughs | The user needs a guided tour of a screen | The same trigger |
| Push permission pre-prompt | Before the system permission dialog | Audience and schedule in the dashboard |
| App update prompt | The user is on an old version | A segment |
| Review prompt | The user reaches a streak milestone | A trigger set by the app |

## 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.

```typescript src/components/HelpButton.tsx theme={null}
export function HelpButton({ triggerValue }: HelpButtonProps) {
  const handlePress = () => {
    OneSignal.InAppMessages.addTrigger('help_topic', triggerValue);
  };

  return (
    <TouchableOpacity onPress={handlePress} style={styles.button} hitSlop={8}>
      <Ionicons name="help-circle-outline" size={26} color={Colors.white} />
    </TouchableOpacity>
  );
}
```

```typescript app/(tabs)/_layout.tsx theme={null}
<Tabs.Screen
  name="index"
  options={{
    title: 'Dashboard',
    headerRight: () => <HeaderRight helpTopic="dashboard" />,
    tabBarIcon: ({ focused }) => <TabIcon name={focused ? 'home' : 'home-outline'} focused={focused} />,
  }}
/>
```

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](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-help.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=521ce92f66d1df24e99790600813523a)

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](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-iam-walkthrough.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=c335375ee2bb79060e97aa945dea644e)

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.

```html docs/iam-html/help-dashboard.html theme={null}
<button id="got-it" class="cta-btn" data-onesignal-unique-label="dashboard-got-it">Got it</button>

<script>
  document.addEventListener("DOMContentLoaded", function () {
    document.getElementById("got-it").addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
  });
</script>
```

## 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](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-iam-push-prompt.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=18791e9af52a803d41048eba393109f6)

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

```html docs/iam-html/push-permission-prompt.html theme={null}
<script>
  document.addEventListener("DOMContentLoaded", function () {
    document.getElementById("enable-btn").addEventListener("click", function (e) {
      OneSignalIamApi.triggerPushPrompt(e);
    });
    document.getElementById("skip-btn").addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
  });
</script>
```

> [!NOTE]
>
> 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](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-iam-app-version.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=f096ce85f566823331171e14312e534d)

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.

```html docs/iam-html/app-update-prompt.html theme={null}
<script>
  var IOS_URL = "https://apps.apple.com/app/id" + IOS_APP_STORE_ID;
  var ANDROID_URL = "https://play.google.com/store/apps/details?id=" + ANDROID_PACKAGE;

  // One message serves both platforms: pick the store from the device.
  var isAndroid = /android/i.test(navigator.userAgent);
  var storeUrl = isAndroid ? ANDROID_URL : IOS_URL;

  document.addEventListener("DOMContentLoaded", function () {
    document.getElementById("update-btn").addEventListener("click", function (e) {
      // openUrl tracks the click, opens the store and closes the message
      OneSignalIamApi.openUrl(e, storeUrl);
    });
    document.getElementById("later-btn").addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
  });
</script>
```

The greeting uses a tag, with a fallback for users who do not have one.

```html docs/iam-html/app-update-prompt.html theme={null}
<p>Hey {{ user_name | default: "there" }}, you're on an older version</p>
```

**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.

> [!NOTE]
>
> 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.

```typescript src/lib/reviewPrompt.ts theme={null}
export async function maybeAskForReview(streak: number): Promise<void> {
  try {
    if (streak <= 0 || streak % STREAK_MILESTONE_DAYS !== 0) return;

    // A second session on the same day leaves the streak unchanged —
    // don't ask twice for the same milestone.
    const lastPrompted = await AsyncStorage.getItem(LAST_PROMPTED_STREAK_KEY);
    if (lastPrompted === String(streak)) return;
    await AsyncStorage.setItem(LAST_PROMPTED_STREAK_KEY, String(streak));

    OneSignal.InAppMessages.addTrigger(REVIEW_TRIGGER_KEY, REVIEW_TRIGGER_VALUE);
    console.log('[reviewPrompt] Trigger set at streak', streak);
  } catch (e) {
    console.warn('[reviewPrompt] maybeAskForReview error:', e);
  }
}
```

**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.

```html docs/iam-html/review-prompt.html theme={null}
<script>
  document.addEventListener("DOMContentLoaded", function () {
    var autoCloseBtn = document.getElementById("auto-close-btn");

    document.getElementById("rate-btn").addEventListener("click", function (e) {
      // Passes the click name "review" to the app's In-App Message click
      // listener, which opens the native rating sheet. addClickName does not
      // close the message, so close it straight afterwards.
      OneSignalIamApi.addClickName(e, "review");
      setTimeout(function () { autoCloseBtn.click(); }, 300);
    });
    autoCloseBtn.addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
    document.getElementById("later-btn").addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
  });
</script>
```

**3. The app opens the native rating sheet**

The click listener checks the name and asks the system to show the sheet.

```typescript src/lib/reviewPrompt.ts theme={null}
export function handleReviewClick(event: InAppMessageClickEvent): void {
  if (event.result.actionId !== REVIEW_ACTION_ID) return;

  // Give the In-App Message a moment to close before presenting the sheet
  setTimeout(async () => {
    try {
      // false on TestFlight builds and on the web
      if (await StoreReview.isAvailableAsync()) {
        await StoreReview.requestReview();
      } else {
        console.log('[reviewPrompt] Store review not available on this build');
      }
    } catch (e) {
      console.warn('[reviewPrompt] requestReview error:', e);
    } finally {
      // Clear the trigger so the message is not re-evaluated this app session
      OneSignal.InAppMessages.removeTrigger(REVIEW_TRIGGER_KEY);
    }
  }, 800);
}
```

```typescript app/_layout.tsx theme={null}
OneSignal.InAppMessages.addEventListener('click', handleReviewClick);
```

![A review prompt in-app message](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-review-prompt.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=90dde058450240f49d42e76402ed28ce)

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.

> [!WARNING]
>
> 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.

> [card] [In-app triggers](https://documentation.onesignal.com/docs/en/iam-triggers.md)
>
> Trigger types and how they combine.

> [card] [HTML in-app messages](https://documentation.onesignal.com/docs/en/design-your-in-app-message-with-html.md)
>
> Design messages with your own HTML.

> [card] [In-app JavaScript API](https://documentation.onesignal.com/docs/en/in-app-message-api.md)
>
> Every `OneSignalIamApi` method.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.