> ## 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: a full OneSignal integration

> Follow one real app, Clean Beans, to see how push, in-app, email, SMS, Live Activities, and Event Streams fit together in Expo with Supabase.

Most OneSignal guides explain one feature at a time. This one follows a single app from end to end and shows how every messaging feature was wired in, with the code that runs in production.

The app is **Clean Beans**, a cleaning rota for shared homes. It is built with Expo (React Native) and uses Supabase for its database, auth, and backend functions. OneSignal handles every message the app sends.

![Three Clean Beans screens: the dashboard, a cleaning session, and the weekly rota](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-dashboard-session-rota.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=f8fc7eac8e69faea6aece66f73c2d820)

Clean Beans: the dashboard, a cleaning session, and the weekly rota.

## What Clean Beans does

A household adds its rooms, and the app turns them into a list of cleaning tasks with sensible frequencies. A rota generator spreads those tasks across the week to fit each person's time budget. Members run cleaning sessions, tick off tasks, build daily streaks, send each other kudos, and compete on a weekly leaderboard.

Cleaning is shared, recurring, and time-bound, which makes it a good fit for almost every kind of message: reminders, social updates, countdowns, recaps, and coaching.

## Why this guide exists

Use it to answer three questions:

* **Which OneSignal feature fits which job?** Each page starts from something the app needed to do, then shows the feature that does it.
* **Where does the code go?** Some work belongs in the app, some on your backend, and some in the OneSignal dashboard. Every example says which.
* **What goes wrong?** Warnings and notes on each page record what was learned by shipping it. One setting, `collapse_id`, was tried and then removed, and [Reliable, well-behaved push](https://documentation.onesignal.com/docs/en/example-full-integration-reliable-push.md) explains why.

## How to read it

The guide is a set of pages, one per topic. You do not need to read them in order. [SDK setup and user identity](https://documentation.onesignal.com/docs/en/example-full-integration-sdk-setup.md) is the foundation for everything else. After that, each page stands on its own.

Most features are presented the same way:

1. **What the user sees**, usually with a screenshot.
2. **How it works**, as a short sequence of who does what.
3. **The code**, taken from the app. The title of each code block is the file it comes from.
4. **Dashboard setup**, where the feature needs configuring in OneSignal.

Limits and surprises are called out in warnings and notes next to the feature they affect.

> [!NOTE]
>
> The code is real, but identifiers are replaced with placeholders such as `YOUR_ONESIGNAL_APP_ID` and `YOUR_PROJECT_REF`. Long files are trimmed to the lines that matter. A line containing only `// ...` marks where code was left out.

## How the pieces fit together

| Where | What it owns | Examples |
| - | - | - |
| **The Expo app** | Anything that needs the device or the signed-in user | Initializing the SDK, asking for permission, identifying the user, tags, custom events, in-app message triggers, handling taps |
| **The Supabase backend** | Anything triggered by a schedule or by data changing | Reminders, social pushes, the weekly email, SMS codes and invitations, starting Live Activities, receiving Event Stream webhooks |
| **The OneSignal dashboard** | Content and targeting that should change without a release | In-app messages, the email template, segments, Conversion Metrics, the Event Stream |

The **External ID** connects all three. Clean Beans sets it to the Supabase user ID at sign-in, so the backend can address any person using an ID it already stores.

![Architecture diagram showing the Expo app, Supabase backend, and OneSignal dashboard](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/clean-beans-architecture.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=b6d5655991cdf5b4de0645b9d7f9cd95)

The app, the backend, and the dashboard each talk to OneSignal. The External ID ties them to one user.

## Feature map

| What the app needed | OneSignal feature | Page |
| - | - | - |
| Know who each device belongs to | External ID, email subscription | [SDK setup and user identity](https://documentation.onesignal.com/docs/en/example-full-integration-sdk-setup.md) |
| Personalize and segment | Tags, custom events, Conversion Metrics | [Tags, custom events, and Conversion Metrics](https://documentation.onesignal.com/docs/en/example-full-integration-tags-events.md) |
| Remind people about tasks | Create message API from scheduled functions | [Sending push from your backend](https://documentation.onesignal.com/docs/en/example-full-integration-backend-push.md) |
| Tell housemates what happened | Create message API from app and database events | [Sending push from your backend](https://documentation.onesignal.com/docs/en/example-full-integration-backend-push.md) |
| Never send a reminder twice | Idempotency keys | [Reliable, well-behaved push](https://documentation.onesignal.com/docs/en/example-full-integration-reliable-push.md) |
| Make each push behave appropriately | Expiry, grouping, interruption levels, badges | [Reliable, well-behaved push](https://documentation.onesignal.com/docs/en/example-full-integration-reliable-push.md) |
| Open the right screen from a tap or a link | Click listener, deep links, Universal Links | [Deep links and notification clicks](https://documentation.onesignal.com/docs/en/example-full-integration-deep-links.md) |
| Let people act straight from a notification | Action buttons, scheduled delivery | [Deep links and notification clicks](https://documentation.onesignal.com/docs/en/example-full-integration-deep-links.md) |
| Coach and prompt people inside the app | In-app messages with triggers and custom HTML | [In-app messages](https://documentation.onesignal.com/docs/en/example-full-integration-in-app-messages.md) |
| Send a weekly recap | Email template with `custom_data` | [Weekly email with custom\_data](https://documentation.onesignal.com/docs/en/example-full-integration-weekly-email.md) |
| Prove a phone number belongs to the user | SMS to a raw phone number, SMS subscription | [SMS: verification codes and invitations](https://documentation.onesignal.com/docs/en/example-full-integration-sms.md) |
| Invite people who do not have the app | SMS and email to raw contacts | [SMS: verification codes and invitations](https://documentation.onesignal.com/docs/en/example-full-integration-sms.md) |
| Show a countdown on the Lock Screen | Live Activities | [Live Activities](https://documentation.onesignal.com/docs/en/example-full-integration-live-activities.md) |
| Keep a history of notifications in the app | Event Streams | [Notification inbox with Event Streams](https://documentation.onesignal.com/docs/en/example-full-integration-inbox.md) |
| Keep app settings in step with unsubscribes | Event Streams (email events) | [Notification inbox with Event Streams](https://documentation.onesignal.com/docs/en/example-full-integration-inbox.md) |

## What you need

* A OneSignal app with push configured for iOS and Android, and email and SMS set up. See [Channel setup](https://documentation.onesignal.com/docs/en/channel-setup.md).
* An Expo app built with EAS Build. The OneSignal SDK needs native code, so Expo Go is not enough. See [Expo SDK setup](https://documentation.onesignal.com/docs/en/react-native-expo-sdk-setup.md).
* Your App ID and an App API key. See [Keys & IDs](https://documentation.onesignal.com/docs/en/keys-and-ids.md).
* A backend that can run code on a schedule and in response to requests. Clean Beans uses Supabase Edge Functions with `pg_cron`. The same patterns apply to any backend.

## Principles that held up

* **Set the External ID first.** Almost every feature here depends on it. Use an ID your backend already stores.
* **Put each job where it belongs.** The app handles the device and the signed-in user. The backend handles schedules and data changes. The dashboard holds anything you want to change without a release.
* **Check before you send.** Every backend send checks the user's preferences and confirms there is something worth saying.
* **Make scheduled sends repeatable.** An idempotency key built from the type, the recipient, and the date turns a retry into a no-op.
* **Route on a type, not a URL.** A `data.type` field keeps old notifications working when screens move.
* **Verify what callers tell you.** A function that sends messages should confirm the facts in your own database first.

## Every feature at a glance

| Feature | Channel | Trigger | Runs in | Main file |
| - | - | - | - | - |
| SDK initialization and permission | Push | App launch | App | `app/_layout.tsx` |
| User identity | All | Sign-in and sign-out | App | `app/_layout.tsx` |
| Email subscription | Email | Sign-in | App | `src/lib/onesignalSync.ts` |
| Opt-in and preferences | Push, email | Settings screen | App and database | `app/notification-settings.tsx` |
| Tags | All | Sign-in, session, profile edit | App | `src/lib/onesignalSync.ts` |
| Custom events | All | Session start and finish | App | `src/lib/onesignalSync.ts` |
| Conversion Metrics | All | Session finish | Dashboard | |
| Daily digest | Push | Hourly schedule | Backend | `supabase/functions/send-daily-digest/` |
| Overdue reminder | Push | Hourly schedule | Backend | `supabase/functions/send-overdue-reminders/` |
| Cleaning reminder | Push | Hourly schedule | Backend | `supabase/functions/send-cleaning-reminder/` |
| Session completed | Push | Call from the app | Backend | `supabase/functions/session-completed/` |
| Kudos | Push | Call from the app | Backend | `supabase/functions/send-kudos/` |
| Join approved | Push | Database trigger | Backend | `supabase/functions/join-approved/` |
| Idempotent sends | Push, email | Every scheduled send | Backend | `supabase/functions/_shared/idempotency.ts` |
| Delivery profiles | Push | Every push | Backend | `supabase/functions/_shared/delivery.ts` |
| Badges | Push | Task pushes | Backend | `supabase/functions/send-daily-digest/` |
| Tap routing | Push | Tap on a push | App | `app/_layout.tsx` |
| Action buttons | Push | Tap on a push button | Backend and app | `supabase/functions/_shared/buttons.ts`, `src/lib/pushActions.ts` |
| Snoozed reminder | Push | Snooze button | Backend | `supabase/functions/snooze-reminder/` |
| Link rewriting | Links | App opened from a URL | App | `app/+native-intent.tsx` |
| Universal Links and App Links | Links | Tap on a web link | App and website | `app.json`, `website/.well-known/` |
| Help overlays and walkthroughs | In-app | Help button | App and dashboard | `src/components/HelpButton.tsx` |
| Push permission pre-prompt | In-app | Dashboard audience | Dashboard | `docs/iam-html/push-permission-prompt.html` |
| App update prompt | In-app | Old app version | Dashboard | `docs/iam-html/app-update-prompt.html` |
| Review prompt | In-app | Streak milestone | App and dashboard | `src/lib/reviewPrompt.ts` |
| Weekly report | Email | Weekly schedule | Backend and dashboard | `supabase/functions/weekly-report/` |
| SMS subscription | SMS | Phone number verified, sign-in | App | `src/lib/phone.ts` |
| Phone verification code | SMS | Call from the app | Backend | `supabase/functions/send-otp/`, `supabase/functions/verify-otp/` |
| Household invitation | SMS, email | Call from the app | Backend | `supabase/functions/send-invite/` |
| Streak warning | Live Activity | Hourly schedule | Backend and widget | `supabase/functions/streak-warning/` |
| Cleaning reminder | Live Activity | Hourly schedule | Backend and widget | `supabase/functions/cleaning-activity/` |
| Notification inbox | Event Streams | Every push sent or clicked | Backend and app | `supabase/functions/inbox-webhook/` |
| Email preference sync | Event Streams | Email unsubscribed, bounced, or reported as spam | Backend | `supabase/functions/inbox-webhook/` |

## Secrets

The backend functions read these from their environment. None of them is ever shipped in the app.

```bash theme={null}
supabase secrets set ONESIGNAL_APP_ID=YOUR_ONESIGNAL_APP_ID
supabase secrets set ONESIGNAL_REST_API_KEY=YOUR_APP_API_KEY
supabase secrets set ONESIGNAL_WEEKLY_TEMPLATE_ID=YOUR_EMAIL_TEMPLATE_ID
supabase secrets set INBOX_WEBHOOK_SECRET=YOUR_SHARED_SECRET
supabase secrets set OTP_HASH_SECRET=A_LONG_RANDOM_STRING    # key for hashing SMS verification codes

# Optional
supabase secrets set ONESIGNAL_SMS_FROM=YOUR_SMS_SENDER      # if no default sender is set in the dashboard
```

> [!WARNING]
>
> Your App API key can send messages to every user. Keep it on your backend. The app itself only needs the App ID.


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