> ## 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.
# Gaming strategies
> Implementation hub for gaming messaging — player IDs, lifecycle Tags, behavioral Custom Events, segments, and Journey playbooks for mobile and live-service games.
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.
Maximize push opt-ins and guide new players to their first meaningful in-game action with a 7-day Welcome Journey.
Drive sessions, DAU, and MAU with event-driven milestones, content updates, and VIP-tier messaging.
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.
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](#identify-your-players-with-external-ids).
Start with `player_name`, `current_level`, `tutorial_completed`, and `vip_status`. They power most starter Journeys. [Jump to section](#tags).
Fire `tutorial_completed`, `level_completed`, `daily_session`, and `purchase_completed` from your game client or backend. [Jump to section](#custom-events).
Player audiences such as New Players, Active Players, High-Value Players, and Churned Players. [Jump to section](#segments).
Welcome onboarding, re-engagement, milestone celebrations, and VIP/spend-based flows. [Jump to section](#journey-examples).
## 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 Auth0 `uid`, 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.
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's `current_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 to `1` when true and **remove it** when false — segment with "tag exists" rather than storing `0`/`false` values.
If you only set up four Tags, start with `player_name`, `current_level`, `tutorial_completed`, and `vip_status`. They power most starter Journeys.
#### 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. Distinct from `loyalty_tier`, which tracks points-based loyalty program tiers (see [Loyalty Journey](./loyalty-journey-mobile-gaming)). |
| `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](./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](./welcome-journey-mobile-gaming#in-app-message-templates)) 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 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 lowercase `snake_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](./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](./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. |
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.
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:
7-day onboarding Journey using `daily_session` and `player_name` — Basic and Advanced paths.
Catch inactive players with cadenced re-engagement before they churn.
Trigger Journeys from `level_completed`, `achievement_unlocked`, `streak_reached`, and other gameplay events.
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](./app-version-update) and [Targeting Android manufacturers that restrict push delivery](./example-target-certain-android-manufacturers-and-devices).
* **Celebrate player achievements.** Trigger event-driven Journeys on `level_completed`, `achievement_unlocked`, `streak_reached`, or other progression Custom Events. Personalize copy with `player_name`, `current_level`, and `clan_name` to make the moment feel earned. For `achievement_unlocked`, use the `rarity` property to scale message intensity — a `legendary` unlock deserves a louder push than a `common` one.
* **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_unlocked` event with `rarity = "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](./example-app-store-review).
* **VIP and whale messaging.** The High-Value Players segment (`vip_status = "1"` OR `total_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](./mobile-first-journeys#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](./push-fallback-method) for the highest-priority moments.
Measure success by Day 1 / Day 7 / Day 30 retention, ARPDAU (average revenue per daily active user), and push CTR by lifecycle stage — not just opens.
## FAQ
### How is this different from the Mobile-first strategy?
[Mobile-first](./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](./using-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](./personalization-custom-event).
### 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](./prompt-for-push-permissions).
### 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](./web-push-setup) and additional segments for cross-platform players on top of this mobile-gaming foundation.
## Related pages
Worked end-to-end onboarding Journey with both basic and advanced data paths.
Pre-built Journey for rewarding player loyalty and driving tier progression.
Welcome, event-driven, and retention Journey patterns shared across mobile-first apps.
Trigger Journeys from gameplay events with Wait Until and Event Matching.
Ask for push opt-in with a benefit-led in-app message before the OS prompt.
Multi-step HTML in-app message with button navigation for tutorial flows.
Add rich image carousels to iOS push for milestone celebrations and content drops.
Target players on outdated app versions and prompt them to update via in-app messages.
Reach players via email or SMS when push delivery fails for high-priority moments.
Push patterns for friend invites, clan and guild activity, mentions, and direct messages.
Trigger native iOS and Android review prompts via in-app messages at peak gameplay moments.
Build streak mechanics that drive daily logins and reward player consistency.
Sister hub for subscription, freemium, and trial-driven mobile apps.