Mobile-first strategies

Implementation hub for mobile-first messaging — External IDs, Tags, Custom Events, segments, and lifecycle Journeys for subscription, freemium, and trial-driven apps.

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.

Implementation roadmap

Work through these steps in order. Each one links to its section below.

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

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

3. Send user actions as Custom Events

   Fire trial_started, core_feature_used, and trial_converted from your app or backend. Jump to section.

4. Build lifecycle Segments

   Lifecycle audiences such as Active Trial, Trial Expiring, and Core feature untouched. Jump to section.

5. 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 Database uid, 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.

For users who install before signing up, the OneSignal-assigned anonymous user ID still ties Tags and behavior to a Subscription. Promote anonymous profiles to authenticated profiles by setting the External ID the moment a user signs up or logs in — that single call merges the anonymous activity (push opt-in, in-app behavior, Tags) with the new identity.

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)

The key distinction between Tags and Custom Events is in their depth and use cases. Tags are properties of a user, such as Name, Account Status, or Location. Events are thing that the user has done, such as Purchasing an Item, Completing a Level, or Inviting a Friend. Both tags and events can be used for segmentation and personalization.

In practice, you will likely use both:

• 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

Mobile-first lifecycle messaging often calls for both depending on the use case. For example, when a user uses (or doesn’t use) a core feature, send the 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 to 1 when true and remove it when false — segment with “tag exists” rather than storing 0/false values.

If you only set up three Tags, start with account_type, trial_end_date, and core_feature_used. They power every starter segment below.

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 (seconds)	Trigger time-based conversion Journeys. Use OneSignal time operators to compare against the current time and send N days before the trial ends.
subscription_start_date	Unix timestamp (seconds)	Drive anniversary and tenure-based messaging for paid users. Pair with time operators.
subscription_renewal_date	Unix timestamp (seconds)	Drive renewal-window messaging (e.g., “renews in 7 days”) and post-expiration win-back. Pair with time operators.
subscription_auto_renew	1 (set when auto-renew is on)	Suppress renewal-prompt messaging for subscribers who will auto-renew. Removing the Tag flags the highest-priority retention moment.

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.
most_used_feature	string (e.g., dashboard, goals, tracking)	The user’s most-used feature over the last 30 days. Personalize re-engagement copy (“It’s been a week since your last {{ most_used_feature }} session”) with a Tag the user actually cares about. Set from your analytics pipeline on a daily or weekly cadence.

Personalization and preferences

Tag	Values	Use
first_name	string	Personalize message content (e.g., Hi {{ first_name | default: 'there' }}).
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 lowercase snake_case for event names and keep them consistent across your app and backend.

Event	Use case
signup_completed	Welcome Journey entry. Carry acquisition_source as a property for source-aware copy.
trial_started	Trial onboarding Journey entry.
onboarding_completed	Exit onboarding Journeys; confirm setup is finished.
core_feature_used	Confirm activation; exit feature-education Journeys. Fired alongside the core_feature_used Tag — the event triggers Journey logic in the moment, the Tag persists state for later segmentation.
aha_moment_reached	Distinct activation milestone when “first use” and “real value realized” differ (e.g., first export, first invite sent, first habit logged). Use as a stronger Journey exit than core_feature_used.
trial_converted	Exit trial-to-paid conversion Journeys; thank-you message.
plan_upgraded	Exit upsell Journeys; expansion thank-you.
plan_downgraded	Retention check-in trigger; precedes churn for many users.
subscription_renewed	Renewal thank-you, retention checkpoint, and dunning Journey exit.
payment_failed	Dunning Journey entry. Carry failure_reason (e.g., card_expired, insufficient_funds) as a property for tailored copy.
payment_succeeded	Dunning Journey exit; renewal confirmation.
subscription_cancelled	Win-back Journey entry. Carry cancel_reason as a property when your billing platform captures it.
support_contacted	Proactive outreach trigger; suppress promotional messaging while the ticket is open.
referral_sent / referral_redeemed	Viral-loop Journeys — thank the sender on send, and onboard the redeemer with referral-aware copy.

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 ten:

Segment	Definition
New Trialists	trial_started event in the last 3 days. Onboarding-burst entry distinct from the broader Active Trial.
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. The user hasn’t hit their Aha moment — the highest-leverage activation segment.
Paid Users	account_type = "paid".
Power Users	Paid Users AND weekly_active_user = "1". Annual-plan upsell and advocacy targets.
Failed Payment	payment_failed event in the last 7 days AND account_type = "paid". Dunning entry.
At-Risk Subscribers	account_type = "paid" AND Last Session > 14 days ago. Distinct from generic re-engagement — the offer and tone differ for paying users.
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 free users.

Mature mobile-first lifecycle setups run 15+ segments. Start with the ten above, then add depth (preferred channel, locale, 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.

Common mobile-first patterns

• Don’t trigger the OS push prompt at install. Capture push opt-in via an in-app message after signup, the tutorial, or first Aha moment so the prompt arrives at a natural beat with context. Use a benefit-led message (“Get notified when your trial features unlock”) rather than the generic OS prompt. See Prompt for push permission with in-app messages.
• Time conversion pushes to the user’s local time. Trial-ending pushes scheduled in server time fire at 3 a.m. for half your audience. Use Intelligent Delivery or Custom time per timezone so reminders land in waking hours.
• Use core_feature_used as a Journey exit, not just an entry. The single biggest welcome-Journey mistake is messaging users who already activated. Add the core_feature_used event (or Tag) as an exit on every onboarding Journey so converted users stop receiving feature-education pushes.
• Cap trial-Journey frequency at one per day. Trials are 7–14 days for most apps. Two pushes a day for that window will tank opt-in. Use a Journey-level frequency cap and let in-app messages carry the higher-frequency nudges.
• Suppress promotional messaging during open support tickets. Listen for support_contacted and add a suppression filter (e.g., “no support_resolved event in last 3 days”) to upsell and renewal Journeys. A renewal nudge during an active complaint reads as tone-deaf.

Measure success by core action completion rate, trial-to-paid conversion rate, and Weekly Active Users (WAU) trend — not just opens or CTR.

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.

How often should I message trial users?

At most one push per day during the trial window, plus in-app messages. Trials are short (typically 7–14 days), and over-messaging during the trial is the fastest way to lose hard-won opt-in. Use a Journey-level frequency cap to enforce this, and watch your push opt-out rate by Journey step — a step with disproportionate opt-outs is the earliest signal you’re being too aggressive.

How do I keep converted users out of conversion Journeys?

Add an exit condition to every conversion Journey on either the trial_converted Custom Event or account_type = "paid". Without an exit, converted users continue receiving “your trial ends in 2 days” pushes — the most common and most damaging onboarding mistake. The same pattern applies to onboarding Journeys: exit on core_feature_used or onboarding_completed so activated users stop seeing feature-education content.

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. Swap trial_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.