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. Most of the messages in this guide are sent by the backend, one request at a time. A Journey is different. It is a sequence built in the OneSignal dashboard that decides for itself who to message, when, and what happens next. Clean Beans uses Journeys for anything that unfolds over hours or days, and for copy and timing that should be changeable without a release. Clean Beans runs seven Journeys. None of them has backend code of its own, apart from the webhook at the end of the last one. The app’s job is to give the Journeys something to work with.

What the app gives a Journey to work with

A Journey can see three things about a person: the custom events they have sent, their tags, and the segments they belong to. It cannot read your database. Anything a Journey needs to react to has to arrive in one of those forms. The session events are covered in Tags, custom events, and Conversion Metrics. The other two events exist only to start a Journey. signed_up fires once per account. The account’s age is checked first, so someone who installs the app on a new phone is not onboarded a second time.
src/lib/onesignalSync.ts
streak_milestone carries the streak length as a number, so the message can show it.
src/lib/onesignalSync.ts
Send an event that starts a Journey only after OneSignal.login() has been called. An event sent before login is recorded against an anonymous user, not the person who is about to sign in. Clean Beans calls trackSignedUpOnce() straight after login() in the same effect. See SDK setup and user identity.

Onboarding: a sequence with a goal

The onboarding Journey has one aim, which is to get a new member to their first cleaning session. Everything in it stops the moment that happens.
1

The app sends signed_up

The member enters the Journey. Each member goes through once.
2

A welcome email and an in-app walkthrough go out straight away

The email lists three steps to get going. The in-app message is shown the next time the member opens the app.
3

Three pushes follow on days 1, 3, and 6

Each one waits for a time window of 10:00 to 19:00 in the member’s own time zone.
4

A completed session ends it

The Journey’s exit rule is the cleaning_session_completed event. Nobody is nudged to do something they have already done.
Dashboard setup. Create the Journey with Custom Event as its entry rule and signed_up as the event. Under exit rules, choose to exit when a custom event occurs and pick cleaning_session_completed. Put a Time Window step before each push so a wait that ends at 03:00 does not send at 03:00.
Choose the goal first and make it the exit rule. A sequence without one keeps talking to people who have already done what it asked.

Session reminder: start on one event, cancel on another

If someone starts a cleaning session and never finishes it, their work is not logged. This Journey starts on cleaning_session_started, waits three hours, and sends a reminder. Its exit rule is cleaning_session_completed, so finishing the session cancels the reminder. This start-and-cancel pair is the simplest useful Journey there is. The same shape fits an abandoned basket, an unfinished sign-up form, or a draft that was never sent.
Check the edge of the time window. The window originally closed at 18:00. A session started at 16:00 would reach the end of its wait at 19:00, find the window shut, and be told “you didn’t finish” at 08:00 the next morning. The window now closes at 21:00. When a message only makes sense on the same day, check what happens to someone who arrives just after the window closes.

Session completed: personalize from the event

When a session ends, the cleaner gets a short confirmation that names the room. The room is not a tag. It comes from the event that started the Journey.
Push template: Cleaning Session Completed
journey.first_event.properties reads a property of the entry event. user_name on its own reads a tag, and the default filter covers anyone whose tag is missing. This Journey is one step long. It could have been a backend send, like the push that tells housemates about the same session in Sending push from your backend. It is a Journey because the wording can then be changed, tested, or switched off in the dashboard.
The Event Stream reports a Journey message as it was written, with the Liquid still in it. The Clean Beans inbox showed {{ journey.first_event.properties.room_name }} cleaned until the webhook learned to render it. See Render Liquid before you store it.

Room-based promos: branch on an event property

This Journey sends a different message depending on which room was cleaned. It shows two things: holding people until an event happens, and branching on a property of that event. Members enter from a segment of people active in the last seven days. The first step is a Wait Until with three branches. Each branch waits for cleaning_session_completed with a particular room_name. A session in any other room matches no branch, and the member keeps waiting. Re-entry is allowed after 30 minutes, so the Journey responds to each new session.
The pushes in this Journey advertise made-up cleaning products. They are there to show the pattern. They are also marketing messages that the app’s notification settings do not cover, which is something to design for in a real app. See What Journeys cannot see.

Streak milestone: an event with a number

The app decides when a streak has reached a milestone, because it has just saved the new streak. It sends streak_milestone with the length, and the Journey does the rest.
Push template: Streak - Milestone reached
Two Journeys, one moment. A milestone always happens at the end of a session, which is also when the session-completed Journey sends. Without the one-minute wait, the two pushes would arrive together. When several Journeys start from the same user action, look at them side by side.

Streak about to break: timing, a segment check, and varied copy

A streak ends at midnight on any day without a session. This Journey warns the member that evening. It is the most involved of the seven, and each of its steps solves a separate problem. Landing on the right evening. The warning belongs on the evening after the last session, whatever time that session was. A wait of 22 hours followed by an 18:00 to 22:00 window always lands there. A session at 08:00 reaches the window step at 06:00 the next day and is held until 18:00. A session at 23:00 reaches it at 21:00 the next day and sends at once. Respecting a setting the Journey cannot see. Clean Beans has a “Streak reminders” switch in its notification settings, stored in the database. The app mirrors it as a tag.
src/lib/onesignalSync.ts
The segment requires streak_count greater than 1 and streak_reminders equal to on. A member on an old build has no streak_reminders tag at all, so they fall outside the segment and are not sent the warning. Varying the copy. The same sentence every evening is easy to stop seeing. The Split step sends each person down one of five branches at random, and each branch has its own template. The branch is chosen again every time someone enters, so a member sees different wording on different evenings.
Clean Beans also shows a streak warning as a Live Activity, described in Live Activities. A member with Live Activities switched on gets both. The push covers Android and anyone who has turned Live Activities off.

Re-engagement and the Journey webhook

The last Journey handles members who have stopped opening the app. It is the only one that enters from a segment alone, and the only one that calls the backend. Re-entry is allowed after 30 days. The entry is limited to people who join the segment after the Journey starts. Without that, everyone already inactive on the day it is switched on receives the first push at once.

Tell your backend when the sequence runs out

A member who reaches the end without cleaning has not responded to four messages. A fifth is unlikely to help. Clean Beans tells the household instead. A Webhook step calls a backend function, which marks the member as inactive and notifies the household’s owners and admins. Dashboard setup. Create a Journey webhook with these settings and select it in the Journey’s last step.
Journey webhook
The function checks the secret before anything else. It is deployed without Supabase’s token check, because OneSignal does not send a Supabase token, so the shared secret is the only thing standing between the endpoint and the public internet.
supabase/functions/journey-webhook/index.ts
It then checks the claim for itself. The Journey says the member is inactive, but the Journey only knows about app sessions and events. The database knows whether they have cleaned.
supabase/functions/journey-webhook/index.ts
Only then does it mark the member and send one push to the people who can do something about it.
supabase/functions/journey-webhook/index.ts
The flag clears itself. A database trigger removes it the next time the member completes a session, so the app never has to remember to.
A webhook step can do anything a message step cannot: update a record, open a support ticket, add someone to a list in another system. Treat the request like any other call from outside. Check a secret, check the facts, and make a repeat harmless.

What Journeys cannot see

Every backend send in this guide checks the member’s notification settings before it sends. A Journey cannot do that, because the settings are in the app’s database. Only the streak warning has a mirrored setting. The other Journey pushes go to anyone with push notifications switched on for the app. If your app has per-type notification settings, mirror each one that a Journey should respect.

Things to know

  • Look for Journeys that share an audience. Clean Beans briefly had two re-engagement Journeys live on the same segment, which put every inactive member in line for both sequences. A second Journey on a segment is easy to switch on and hard to notice.
  • Give Journey pushes a URL and a data.type. Templates created in the dashboard have neither by default, so a tap only opens the app. Clean Beans sets both on every Journey template, so they route like the backend’s pushes. See Deep links and notification clicks.
  • An active Journey can be edited, and the edit can affect people already in it. Clean Beans changed a time window and added a wait on Journeys that were running. Make changes like that deliberately.
  • Journey messages count in the inbox. They arrive through the same Event Stream as every other push, with their Liquid unrendered.
  • Turn off click tracking on an email whose button is a Universal Link. Tracking rewrites links to pass through a tracking domain, and a rewritten link no longer opens the app. See Open the app from ordinary web links.

Journeys overview

Entry rules, steps, and how a Journey runs.

Journey settings

Who enters, exits, and re-enters.

Journey actions

Wait, Wait Until, Yes/No, Split, and Time Window.

Journey webhooks

Call your own server from a Journey step.

Personalize with custom events

Use event properties in Journey messages.

Event-driven Journeys

Design Journeys that respond to behavior.