A mobile-first messaging strategy targets apps where the majority of the user experience lives on a phone — most commonly subscription, freemium, and trial-driven apps. If your app’s primary surface is the phone and your growth depends on in-app engagement, this guide is for you. This page is the implementation hub: which identifier to set, what data to collect, which segments to build, and which Journeys drive trial-to-paid conversion and retention. Each section links to the canonical docs for deeper detail.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.
Implementation roadmap
Work through these steps in order. Each one links to its section below.Assign External IDs
Set a stable, app-side identifier on every authenticated user so push, email, and SMS tie to one profile across reinstalls. Jump to section.
Add user properties as Tags
Start with
account_type, trial_end_date, and core_feature_used. These three power every starter segment. Jump to section.Send user actions as Custom Events
Fire
trial_started, core_feature_used, and trial_converted from your app or backend. Jump to section.Build lifecycle Segments
Lifecycle audiences such as Active Trial, Trial Expiring, and Core feature untouched. Jump to section.
Create lifecycle Journeys
Welcome, trial-to-paid conversion, retention, and win-back. Jump to section.
Identify your users with External IDs
External IDs preserve identity across installs and tie push, email, and SMS to one customer profile. Use the unique identifier from your authentication or billing platform — for example, an Auth0 or Databaseuid, or a Stripe customer_id.
Set the External ID at signup, on every login, and on session resume. The OneSignal SDK does not assign it for you, and assigning it late or sporadically breaks trial-to-paid attribution across reinstalls.
External ID setup
Assign a unique identifier to each user so data follows them across devices and reinstalls.
Recommended data
Tags and Custom Events are both ways to add data to your users. However, there are some key differences:| Feature | Tags | Custom Events |
|---|---|---|
| Data usage | Segmentation and personalization | Trigger Journeys without a Segment, Wait Until steps, personalization directly within Journeys |
| Data retention | Lifetime | 30+ days (lifetime storage is available) |
| Data format | Key-value strings or numbers | JSON |
| Data source | OneSignal SDK, API, or CSV import | OneSignal SDK, API, or integrations |
| Data access | Segmentation and message personalization | Journeys and Journey-message-template personalization, Segmentation (Coming soon) |
- Tags for user properties that are static and don’t change often
- Custom Events for real-time scenarios, complex segmentation, and more sophisticated journey workflows
core_feature_used event (to trigger a Journey or measure activation). You may also want to set a core_feature_used = "1" Tag to segment and track users later.
Tags
Tags persist on the user profile and are used for segmentation and personalization. For boolean-style signals, set the Tag to1 when true and remove it when false — segment with “tag exists” rather than storing 0/false values.
Lifecycle state
| Tag | Values | Use |
|---|---|---|
account_type | free / trial / paid / lapsed | Lifecycle state — drives Journey entry, exit, and audience filters. |
plan_tier | basic / pro / enterprise (your tiers) | Tailor upsell, renewal, and feature messaging by plan tier. |
trial_end_date | Unix timestamp in seconds | Trigger time-based conversion Journeys. Use OneSignal time operators to compare against the current time and send N days before the trial ends. |
Engagement
| Tag | Values | Use |
|---|---|---|
core_feature_used | 1 (set when used) | Confirms the user has hit their Aha moment. Absence is your highest-leverage adoption segment — these users carry the highest churn risk. |
weekly_active_user | 1 (set when WAU) | Identify Power Users for upsell or annual-plan offers. |
Personalization and preferences
| Tag | Values | Use |
|---|---|---|
first_name | string | Personalize message content (e.g., Hi {{first_name}}). |
acquisition_source | referral / social / organic / paid | Tailor onboarding messaging to where the user came from. |
content_pref_<category> | 1 | Per-category content preferences (e.g., content_pref_marketing, content_pref_entertainment). Set when the user opts in; absence means not opted in. |
Add user data tags
Add key-value pairs to user profiles for segmentation and personalization.
Custom Events
Send a Custom Event for each moment you want to react to. Events are stored shorter-term than Tags but can carry properties, making them ideal for Journey entry triggers and conversion tracking. Use lowercasesnake_case for event names and keep them consistent across your app and backend.
| Event | Use case |
|---|---|
trial_started | Welcome and onboarding Journey entry |
trial_converted | Exit conversion Journeys; thank-you message |
subscription_cancelled | Win-back Journey entry |
onboarding_completed | Exit onboarding Journeys; confirm Aha moment |
core_feature_used | Confirm activation; exit feature-education Journeys |
payment_failed | Dunning Journey entry |
plan_upgraded | Exit upsell Journeys; expansion thank-you |
Custom Events
Capture user actions and use them to trigger Journeys or Wait Until steps.
Segments
Combine Tags and Custom Events into segments. Start with these seven:| Segment | Definition |
|---|---|
| Active Trial | account_type = "trial" AND trial_end_date more than 3 days from now |
| Trial Expiring | account_type = "trial" AND trial_end_date within the next 3 days |
| Core feature untouched | core_feature_used does not exist (user hasn’t hit their Aha moment) |
| Paid Users | account_type = "paid" |
| Power Users | Paid Users AND weekly_active_user = "1" |
| Lapsed | account_type = "lapsed". Keep active for 60 days post-cancellation, then exit users to a long-tail dormant list. |
| Re-engagement | OneSignal’s built-in Last Session filter: more than 7 days for trial users, more than 14 days for paid users. |
Mature mobile-first lifecycle setups run 15+ segments. Start with the seven above, then add depth (push opt-in status, plan tier, session frequency) as your Journeys grow.
Segmentation
Group users by shared characteristics to target Journeys and campaigns.
Journey examples
With Tags, Custom Events, and segments in place, build Journeys against them. Mobile-first Journeys mix channels by intent — push and in-app for real-time nudges, email for deeper conversion content, and SMS for high-intent moments like trial expiration and renewal. The lifecycle has four core flows:Welcome and onboarding
Engage new users immediately and drive them to their Aha moment before the trial expires.
Trial-to-paid conversion
Time-based conversion sequences as the trial clock runs down.
Retention and re-engagement
Catch at-risk users with
Last Session thresholds before they fully disengage.Win-back
Re-engage churned subscribers with a value reminder rather than a discount.
FAQ
Should I use a Tag or a Custom Event for a given signal?
Use a Custom Event when you want to trigger a Journey or count an occurrence (e.g.,trial_started, core_feature_used). Use a Tag when you want to segment on the user’s current state or set a Journey exit condition (e.g., account_type = "trial", core_feature_used = "1"). Many signals deserve both — fire the event in the moment, then update the Tag to reflect the new state.
Do I need data integrations to use lifecycle Journeys?
No. You can build effective welcome and retention Journeys using dashboard-only segments like “First Session” and “Last Session.” Custom Events and Tags give you more precise triggers and exit conditions, but they are not required to get started.Does this guide apply to apps with a web or desktop surface?
The patterns here apply to any subscription or freemium product, but the channel mix shifts. Apps with a meaningful web or desktop surface should layer in web push and additional segments for cross-platform users on top of this mobile-first foundation.What about apps with one-time purchases or DLC instead of subscriptions?
The patterns apply, but the trial-specific Tags and Custom Events do not. Swaptrial_end_date for last_purchase_date, trial_started and trial_converted for first_purchase_completed, and the Trial Expiring segment for an at-risk segment based on Last Session. For high-value users, replace weekly_active_user with a spend-based Tag like total_spend_cents or purchase_count. See Welcome Journey: Mobile gaming for an end-to-end Journey shaped around purchases instead of subscriptions.
Related pages
Mobile-first lifecycle Journeys
Welcome, conversion, retention, and win-back Journey examples for mobile-first apps.
Journeys overview
How automated messaging flows work in OneSignal.