A gaming strategy targets apps where the experience is play-driven — from casual mobile games to RPGs and live-service titles. If your success depends on session frequency, in-app spend, and player retention curves, this guide is for you. This page is the implementation hub: which player identifier to set, what gameplay data to capture, which segments to build, and which Journeys drive onboarding, retention, and monetization. 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.
Onboard
Maximize push opt-ins and guide new players to their first meaningful in-game action with a 7-day Welcome Journey.
Engage
Drive sessions, DAU, and MAU with event-driven milestones, content updates, and VIP-tier messaging.
Re-engage
Win back lapsed players on a Day 1, 3, 7, 14 cadence before they cross into churn.
Implementation roadmap
Work through these steps in order. Each one links to its section below.Assign External IDs to players
Set a stable player ID on every authenticated player so push, email, and SMS tie to one profile across devices and reinstalls. Jump to section.
Add player properties as Tags
Start with
player_name, current_level, tutorial_completed, and vip_status. They power most starter Journeys. Jump to section.Send player actions as Custom Events
Fire
tutorial_completed, level_completed, daily_session, and purchase_completed from your game client or backend. Jump to section.Build lifecycle Segments
Player audiences such as New Players, Active Players, High-Value Players, and Churned Players. Jump to section.
Create lifecycle Journeys
Welcome onboarding, re-engagement, milestone celebrations, and VIP/spend-based flows. Jump to section.
Identify your players with External IDs
External IDs preserve identity across installs and tie push, email, and SMS to one player profile. Use the unique identifier from your account, auth, or game-services platform — for example, your game’s player ID, an Auth0uid, or a PlayFab/Game Center identifier.
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 reinstall-to-reward attribution.
External ID setup
Assign a unique player identifier so progression, purchases, and notifications follow the player across devices and reinstalls.
Recommended data
Tags persist on the player profile (current state); Custom Events record discrete moments (what just happened). Use both — Tags drive segmentation and personalization, Custom Events trigger Journey entry and Wait Until steps. Gaming leans heavily on both. A player’scurrent_level and vip_status are Tags you segment on, while level_completed and purchase_completed are events that trigger celebration or upsell Journeys.
Tags
Tags persist on the player 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 and progression
| Tag | Values | Use |
|---|---|---|
current_level | integer (as string) | Track progression. Drives content gating, level-up celebration Journeys, and difficulty-tuned messaging. |
rank_tier | bronze / silver / gold / platinum / diamond (your tiers) | Competitive ranking. Drives rank-up celebration Journeys and tier-specific content, balance, and event messaging. |
tutorial_completed | 1 (set when finished) | Confirms onboarding completion. Absence is the highest-leverage adoption segment. |
account_type | free / paid / lapsed | Lifecycle state for free-to-play conversion and lapsed-player win-back. |
vip_status | 1 (set for VIPs) | Identifies high-value players for premium offers, early access, and concierge messaging. |
Engagement and spend
| Tag | Values | Use |
|---|---|---|
total_spend_cents | integer (as string) | Lifetime value. Power whale and high-spender segments. |
last_purchase_date | Unix timestamp (seconds) | Spend recency. Use time operators to send win-back offers a fixed number of days after the last purchase. |
streak_count | integer (as string) | Daily login or play streak. Drives streak-protect reminders and milestone rewards. |
claimed_new_user_offer | 1 (set when claimed) | Tracks whether the player has redeemed a starter pack or new-user bundle. Use to gate IAMs (e.g., the Day 3 new-player loot box) so redeemers don’t see the offer twice. |
favorite_game_mode | string (e.g., pvp, campaign, casual) | Personalize content recommendations and event invitations. |
Personalization
| Tag | Values | Use |
|---|---|---|
player_name | string | Personalize message copy (e.g., Hey {{ player_name | default: 'hero' }}). |
clan_name | string | Reference the player’s clan, guild, or team in social and event copy. |
acquisition_source | string (e.g., paid_social, organic, referral, cross_promo) | Optional but high-value for UA-driven games. Vary onboarding copy by acquisition channel — paid social users respond differently than organic, and cross-promo installs may already know your studio. |
Add user data tags
Add key-value pairs to player profiles for segmentation and personalization.
Custom Events
Send a Custom Event for each gameplay 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 Wait Until conditions. Use lowercasesnake_case for event names and keep them consistent across your client and backend.
| Event | Use case |
|---|---|
tutorial_completed | Exit onboarding Journey; confirm first-session activation. |
level_completed | Discrete event fired each time a player completes a level — separate from the persistent current_level Tag. Use as a Journey entry rule or Wait Until anchor for milestone celebrations. Carry level_number, score, and time_to_complete as properties for personalized copy. |
achievement_unlocked | Milestone celebration. Use as a Journey entry rule and carry achievement_id, achievement_name, and rarity (e.g., common / rare / legendary) as properties for personalized copy and rarity-tier targeting. |
daily_session | Wait Until anchor for daily re-engagement loops. Dedupe to once per calendar day in the player’s timezone. |
reward_claimed | Stronger signal than daily_session for retention loops — fires only when the player actually claimed the daily reward. Use as the Wait Until anchor in the Welcome Journey: Mobile gaming when your game has an explicit “Claim” action. |
purchase_completed | In-game purchase. Drives thank-you push, receipt email, and upsell-timing refresh. Carry product_id, price, currency, and is_first_purchase as properties so messages can reference what was bought and trigger first-purchase Journeys. |
streak_reached | Reward push referencing the achievement. |
cart_abandoned | Recovery push on the expiration branch of a Wait Until. |
friend_invited / friend_joined | Social moments; cross-promote viral mechanics. See Social activity for the broader pattern — likes, mentions, comments, follows, and direct user-to-user messages. |
live_event_started | Live-service event launch (raids, festivals, limited-time modes). Drives launch broadcasts to active and at-risk players, and reminders 1–2 days before the event ends. Carry event_id, event_name, and ends_at as properties. |
Custom Events
Capture player actions and use them to trigger Journeys or Wait Until steps.
Segments
Combine Tags and Custom Events into segments. Start with these nine:| Segment | Definition |
|---|---|
| New Players | First Session < 7 days ago. Entry audience for onboarding and welcome flows. |
| Tutorial incomplete | tutorial_completed does not exist. Highest-priority activation segment. |
| Active Players | Last Session < 3 days ago. Daily-active core for live events and content drops. |
| Progressing Players | level_completed Custom Event fired in the last 7 days. Players actively advancing through content — distinct from Active Players, which only measures session recency. Reward with content drops and difficulty-tuned messaging. |
| Power Players | Active Players AND streak_count > 5. Reward and retention-protect targets. |
| High-Level Players | current_level >= 50 (use whatever level marks your endgame). Endgame audience for advanced tips, mentor programs, beta access, and late-game content drops. |
| At-Risk Players | Last Session > 7 days ago AND Last Session < 14 days ago. The window where re-engagement still works. |
| Churned Players | Last Session > 14 days ago. Win-back territory; back off general messaging. |
| High-Value Players | vip_status = "1" OR total_spend_cents > 5000. Premium offer audience — also referred to as VIPs or whales. |
Mature gaming setups run 15+ segments split by game mode, content preferences, region, and platform. Start with the nine above, then add depth (push opt-in status, hardware tier, content pack ownership) as your Journeys grow.
Segmentation
Group players by shared characteristics to target Journeys and campaigns.
Journey examples
With Tags, Custom Events, and segments in place, build Journeys against them. Gaming Journeys mix channels by intent — push and in-app for in-the-moment nudges, email for recaps and milestone moments, and SMS sparingly for high-intent moments like VIP launches or limited-time events. The lifecycle has four core flows:Welcome Journey: Mobile gaming
7-day onboarding Journey using
daily_session and player_name — Basic and Advanced paths.Re-engagement (Day 1, 3, 7, 14)
Catch inactive players with cadenced re-engagement before they churn.
Event-driven milestones
Trigger Journeys from
level_completed, achievement_unlocked, streak_reached, and other gameplay events.VIP and high-value players
Run a parallel high-touch Journey for the High-Value Players segment — exclusive offers, early access, and
purchase_completed-driven upsells.Common gaming patterns
- Communicate game updates. Studios ship new levels, content, and gameplay regularly, but automatic OS updates mean players often don’t know. Push and in-app messaging surface what’s new and entice players to explore. Time updates to your Active Players segment, not your full audience. For implementation patterns, see App version update prompts and Targeting Android manufacturers that restrict push delivery.
- Celebrate player achievements. Trigger event-driven Journeys on
level_completed,achievement_unlocked,streak_reached, or other progression Custom Events. Personalize copy withplayer_name,current_level, andclan_nameto make the moment feel earned. Forachievement_unlocked, use therarityproperty to scale message intensity — alegendaryunlock deserves a louder push than acommonone. - App store review prompts. Ask for App Store and Google Play reviews at peak moments — immediately after a hard-won boss kill, a major level milestone, or an
achievement_unlockedevent withrarity = "legendary". The post-win window is the highest-converting time to ask. Use the native iOS and Android review modals via in-app messages so players never leave the game. See Get more app store reviews. - VIP and whale messaging. The High-Value Players segment (
vip_status = "1"ORtotal_spend_cents > 5000) is your VIP/whale audience. Run a parallel high-touch Journey for those players — exclusive offers, early access,purchase_completed-driven thank-yous, and concierge channels. - Re-engagement cadence. A common cadence is Day 1, Day 3, Day 7, Day 14 of inactivity. The first three windows still convert; Day 14 is the boundary between re-engagement and win-back. See Retention Journeys for the implementation. Effective re-engagement messages give players a concrete reason to return — a new level or content drop with a specific hint about what’s new, a free in-game item (coins, tokens, energy), a limited-time offer, an upcoming seasonal or sponsored live event, or a streak-protect reminder. When push delivery fails (uninstalled, opted out, sleeping device), fall back to email or SMS for the highest-priority moments.
FAQ
How is this different from the Mobile-first strategy?
Mobile-first targets subscription, freemium, and trial-driven apps where success is measured by trial-to-paid conversion and recurring engagement. Gaming is mobile-first by definition, but the lifecycle is shaped around session frequency, progression, and in-app purchases rather than trial conversion. The data foundation (External IDs, Tags, Custom Events, segments) is the same; the audiences and Journey shapes differ.Should I use a Tag or a Custom Event for a given gameplay signal?
Use a Custom Event when you want to trigger a Journey or count an occurrence (e.g.,level_completed, purchase_completed). Use a Tag when you want to segment on the player’s current state (e.g., current_level = "10", vip_status = "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 active players?
Daily push is acceptable for active players inside a structured Journey (welcome, re-engagement, live event), but each push needs to carry value — a content drop, a milestone, an offer, or a personalized progression cue. Generic “come back” pushes burn opt-in. Watch your push opt-out rate by Journey step; that’s the earliest signal you’re being too aggressive.How do I personalize messages with player progress or items?
Use Liquid syntax to pull Tag values into push, email, and IAM copy. Common gaming patterns:Hey {{ player_name \| default: 'hero' }}, Your level {{ current_level }} reward is ready, {{ clan_name }} is calling. For event-driven Journeys, the Custom Event payload is also available — see Personalization with Custom Events.
How do I maximize push opt-in for new players?
Don’t trigger the OS prompt at install. Capture push opt-in via an in-app message after onboarding (signup, tutorial, profile setup) so the prompt arrives at a natural beat with context. Use a benefit-led message (“Get notified when daily rewards drop”) rather than the generic OS prompt. See Prompt for push permission with in-app messages.What about apps that mix gaming with other surfaces (e.g., a companion web app)?
The patterns here apply, but the channel mix shifts. Companion web surfaces should layer in web push and additional segments for cross-platform players on top of this mobile-gaming foundation.Related pages
Welcome Journey: Mobile gaming
Worked end-to-end onboarding Journey with both basic and advanced data paths.
Loyalty Journey: Mobile gaming
Pre-built Journey for rewarding player loyalty and driving tier progression.
Mobile-first lifecycle Journeys
Welcome, event-driven, and retention Journey patterns shared across mobile-first apps.
Event-driven Journeys
Trigger Journeys from gameplay events with Wait Until and Event Matching.
Prompt for push permissions
Ask for push opt-in with a benefit-led in-app message before the OS prompt.
Onboarding carousel
Multi-step HTML in-app message with button navigation for tutorial flows.
iOS image carousel push
Add rich image carousels to iOS push for milestone celebrations and content drops.
App version update prompts
Target players on outdated app versions and prompt them to update via in-app messages.
Push fallback to email or SMS
Reach players via email or SMS when push delivery fails for high-priority moments.
Social activity
Push patterns for friend invites, clan and guild activity, mentions, and direct messages.
Get more app store reviews
Trigger native iOS and Android review prompts via in-app messages at peak gameplay moments.
Mobile-first strategies
Sister hub for subscription, freemium, and trial-driven mobile apps.