Mobile-first lifecycle Journeys

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.

This guide implements the Mobile-first strategy as five lifecycle Journeys: welcome, trial-to-paid conversion, event-driven, retention, and win-back. Each Journey supports two implementation paths so you can ship value before all your Custom Event tracking is in place:

• Case 1 – Basic: Use only the data the OneSignal SDK collects automatically — First session, Last session, and built-in Subscription attributes. No Custom Events or Tags required.
• Case 2 – Advanced: Use Custom Events and Tags for behavior-triggered, per-user personalization.

Start with Case 1 and layer in Case 2 components as your data integrations mature.

​

Prerequisites

Work through the Mobile-first strategy implementation roadmap before building Journeys here. The strategy page defines the data foundation; this page implements it. Required:

• External IDs assigned at signup, login, and session resume — see External ID setup.
• Access to Journeys in your OneSignal dashboard.
• At least one configured channel: push (with permission prompted), email, or SMS.

Recommended:

• An in-app message that prompts for push permission — required for the Case 1 welcome flow’s first step.
• Case 2 only:
  • Core Tags: account_type, core_feature_used, trial_end_date — see Tags.
  • Core Custom Events: signup_completed, core_feature_used, trial_converted, subscription_cancelled — see Custom Events.
  • Starter segments: Active Trial, Trial Expiring, Core feature untouched, At-Risk Subscribers, Lapsed — see Segments.

If you don’t have Custom Events yet, build the Case 1 versions of welcome, retention, and win-back while your event tracking comes online. Trial-to-paid conversion requires a trial_end_date Tag in both cases.

​

Welcome Journeys

The welcome Journey’s job is to set new users up for success — drive them to their “Aha!” moment before they churn. The first 7 days determine whether a new user becomes a long-term customer or a churn statistic, so the welcome Journey runs across the full week with gentle daily nudges. Four principles drive the structure:

1. Capture permissions early. Drive push opt-in via a Day 1 in-app message during or right after onboarding. Without push permission, every later welcome step that uses push goes unread.
2. Introduce the product. Pair the IAM with a Day 1 email for consenting users that introduces what the product does, what to do next, and what messages to expect from you.
3. Nudge toward the core feature daily. Days 2–6 each carry a single, gentle reminder tied to a feature, use case, or setup step — never a streak claim or a hollow “we miss you.”
4. End the week deliberately. A Day 7 closing email recaps the user’s first week and transitions them from “trying the product” to “part of the community.”

​

Welcome Journey configuration

Both cases share segments, templates, and Journey settings. Build them once and reference from either case.

​

Welcome Journey segments

Entry:

• Case 1: Built-in segment First Session < 1 day ago AND Last Session > 4 hours ago. The user matches the moment they cross 4 hours of inactivity inside their first day — exactly when the Day 1 message sequence should fire, not the moment of signup.
• Case 2: Custom Event entry on signup_completed (or trial_started for trial-based apps), then a 4-hour Wait so the first message lands after the user finishes their initial session.

Recent activity check (Case 1 only):

• Name: “Active in the last 12 hours”
• Filter: Last Session < 12 hours ago

The Day 2–7 Yes/No branches use this segment to skip the daily push if the user has already been active. Twelve hours is a deliberate compromise — long enough that the user feels like they “just used” the app, short enough that yesterday’s evening session doesn’t suppress today’s nudge. Exit conditions:

• Case 1: Time-based — Journey completes after the Day 7 closing email.
• Case 2: Event-based — exit on core_feature_used = "1" or onboarding_completed. Users who activate stop receiving feature-nudge messages.

​

Welcome Journey templates

These templates are starting points — clone, edit, and re-use them in your own Journey. They use Liquid syntax for personalization.

​

Welcome Journey settings

Entry and exit rules are covered in Welcome Journey segments above. In addition, configure these Journey-level settings:

• Future additions only: Checked — so existing users aren’t bulk-enrolled the moment the Journey is saved.
• Re-entry rules: Disabled — each user receives this Journey only once.

​

Daily timing: Wait + Time Window (Case 1)

Case 1 uses two Journey actions together to deliver a daily nudge during the user’s most likely engagement window:

1. Wait: A fixed delay between days.
2. Time Window: A delivery window in the user’s local timezone (default: 6 PM – 10 PM). Each day’s push is held until the window opens.

Set the Wait to the Time Window duration + a 2-hour buffer. For a 4-hour evening window, the Wait is 6 hours — the buffer guarantees the Wait always expires after the window closes, so the next push is held for the following day rather than re-firing the same evening. See Welcome Journey: Mobile gaming for the full timing math.

​

Trial-to-paid conversion

The trial-to-paid Journey converts trial users to paying subscribers in the days before their trial ends. Where the Welcome Journey teaches the product, this Journey closes the deal — value reminders, time pressure, and a clear upgrade ask calibrated to where the user is in the trial. Three principles drive the structure:

1. Time pressure beats discount. A trial-ending reminder converts higher than a blanket “20% off” email. Use trial_end_date for a real countdown; reserve discounts for the final day or the win-back Journey.
2. Activation status changes the message. A trial user who hit the core feature gets “Keep going — your data and progress carry over”; one who didn’t gets “Try {{ core_feature_name }} before your trial ends — it’s the part most subscribers love.” Same Journey, branched copy.
3. Exit on conversion, immediately. Add an exit on trial_converted (or account_type = "paid") so converted users stop receiving “trial ending” pushes. This is the single most damaging conversion-Journey mistake — see the mobile-first FAQ for the suppression pattern.

​

Trial-to-paid configuration

Entry rules:

• Case 1: account_type = "trial" AND trial_end_date within the next 7 days (the Trial Expiring segment from the strategy page, with the threshold widened from 3 days to 7).
• Case 2: Custom Event entry on trial_started with a Wait until 7 days before trial_end_date using time operators. Cleaner attribution — entry timestamp matches the trial’s actual start, not the moment OneSignal evaluated the segment.

Exit rules:

• Both cases: Exit when trial_converted Custom Event fires or account_type = "paid". Whichever your billing pipeline updates first triggers the exit.
• Both cases: Also exit on subscription_cancelled so users who explicitly cancel their trial don’t get further reminders.

Re-entry rules: No — most trials are single-use. Apps that offer trial extensions should set re-entry per business policy. Future additions only: Checked — keep this on so users mid-trial when the Journey is created don’t get bulk-enrolled into a 7-day cadence partway through.

​

Trial-to-paid templates

Keep every push and email deep-linked to the upgrade screen — see Deep linking. The fewer taps between message and conversion, the higher the rate.

​

Event-driven Journeys

Event-driven Journeys react to specific actions in real time. They’re entirely Case 2 territory — you need Custom Events flowing into OneSignal to use them. Common mobile-first event-driven patterns:

​

Dunning: payment recovery

A representative event-driven shape that almost every subscription app needs. Failed renewal payments are involuntary churn — most users want to keep paying but have an expired card or a temporary decline. A short dunning Journey recovers the majority of these. The full pattern guide — entry rules, Wait Until with Event Matching, threshold modeling, and Liquid personalization — lives on Event-driven Journeys. For mobile-specific welcome and retention shapes that include event-driven steps, see Case 2 in the Welcome and Retention sections on this page.

​

Retention Journeys

Retention catches active users who are slipping before they fully disengage. Two triggers matter for mobile-first apps:

• Inactivity — the user hasn’t opened the app in N days
• Core feature dormancy — the user is opening the app, but hasn’t engaged with the core feature in N days (Case 2 only — needs the core_feature_used Tag)

​

Retention Journey configuration

Both cases share segment shape; the difference is granularity. Entry trigger:

• Case 1: Built-in segment Last Session > 7 days.
• Case 2: Combine Last Session > 7 days with account_type to split trial users (7 days) from paid users (14 days). Optionally add a parallel Core feature untouched segment for feature-dormant users.

Cadence (both cases): Exit conditions:

• Both cases: Auto-exit when the user opens the app (segment membership ends).
• Case 2: Also exit on subscription_cancelled event so the user moves to the win-back funnel without overlap.

​

Core feature dormancy (Case 2 only)

A user who’s actively opening the app but never touching the core feature is a different kind of risk than one who’s just inactive. They’ve passed the install hurdle but stalled before activation — re-engagement copy aimed at “we miss you” misses the actual problem. Use the Core feature untouched segment from Mobile-first strategy — core_feature_used does not exist — combined with Last Session < 7 days so you only message users who are opening the app.

​

Win-back Journeys

Win-back targets users who have already churned — cancelled, lapsed, or expired — and aims to bring them back. The audience and goal are different from Retention: retention prevents churn for users still on a paid plan, while win-back recovers users who are no longer paying. Run them as separate Journeys with different exit conditions so a user can’t sit in both at once. Three principles drive the structure:

1. Lead with value, not discount. A “what you’ve been missing” message converts higher than a generic discount the first time. Reserve discounts for the second touch — discounting on day one trains users to cancel and wait for a coupon.
2. Cap the active window. Run win-back for 60 days post-cancellation, then exit users to a long-tail dormant list. Past 60 days, the unsubscribe risk outweighs the recovery upside.
3. Differentiate by past value. A high-LTV churned user (former VIP, long tenure, high spend) deserves a richer offer than a one-month trial that lapsed. Case 2 splits the cadence by total_spend_cents or tenure.

​

Win-back configuration

Entry rules:

• Case 1: Built-in segment account_type = "lapsed". Most billing pipelines flip the Tag from paid to lapsed on the cancellation date or at the end of the paid period.
• Case 2: Custom Event entry on subscription_cancelled, with a 7-day Wait before the first message. The 7-day buffer lets the immediate-regret cancellations pass — those users either resubscribe on their own or were never going to come back.

Exit rules:

• Both cases: Exit when account_type returns to paid, OR when trial_started or subscription_renewed Custom Event fires. Any of these mean the user is back; stop messaging.
• Both cases: Hard exit at 60 days post-entry. Configure as a final step or a Journey-level timeout — depending on your dashboard, this might be a Wait: 60 days followed by a Tag User step that adds winback_completed = "1" so the user can be excluded from re-entry.

Re-entry rules: Allow re-entry — a user who churns, returns, then churns again should re-enter the Journey on the new cancellation.

​

Win-back templates

​

FAQ

​

Should I build all five Journeys at once?

No — sequence them by leverage and data readiness:

1. Welcome Journey (Case 1) first — highest leverage on long-term retention, requires no Custom Events.
2. Retention Journey (Case 1) once you have at least 30 days of session data so you can tune the inactivity threshold.
3. Trial-to-paid conversion as soon as trial_end_date is reliably set on every trial user.
4. Win-back Journey once your billing pipeline reliably flips account_type to lapsed on cancellation.
5. Event-driven Journeys (purchase, milestone, dunning) as your Custom Event tracking matures.

Each new Journey should reference the exit conditions of the others so users don’t sit in two at once — see the next FAQ.

​

How do I prevent a user from receiving overlapping Journeys?

Use exit conditions that map to Journey progression:

• Welcome exits when core_feature_used = "1" or onboarding_completed.
• Trial-to-paid exits when trial_converted or account_type = "paid". Also exits on subscription_cancelled so cancelled trials don’t keep getting reminders.
• Retention only enters when Last Session > 7 days AND account_type is trial or paid. Exits on app open or subscription_cancelled.
• Win-back only enters when account_type = "lapsed" (or on subscription_cancelled event). Exits on account_type = "paid", subscription_renewed, or 60-day timeout.

Re-entry rules on Journey settings prevent the same user from re-entering an active flow. See Re-entry rules.

​

Can I build these Journeys without Custom Events or Tags?

Yes — the Case 1 versions of Welcome, Retention, and Win-back use only built-in segments (First Session, Last Session, account_type) and require no Custom Events. Trial-to-paid requires the trial_end_date Tag in both cases. Event-driven Journeys (purchase confirmation, milestones, dunning) all require Custom Events.

​

Where should email warm-up fit in the rollout?

Before sending any Welcome or Retention email at scale on a new sending domain. See Email warm-up. For double opt-in flows that confirm subscribers before adding them to your sending list, see Set up confirmed opt-in for email.

​

How frequently should I message users in onboarding?

A common starting point is one message per day for the first 3 days, then drop to every 2–3 days. Watch unsubscribe rate and push opt-out rate at each step — those tell you sooner than open rate whether you’re being too aggressive.

​

Do I need to use all three channels (push, email, SMS)?

No. Push and in-app are the foundation for mobile-first. Email layers in for consenting users when you have longer-form content (welcome, weekly digest, conversion). SMS is reserved for urgent, high-intent moments. Most apps run effectively on push + email.

​

Related pages