Loyalty Journey: Mobile Gaming

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.

A Loyalty Journey is an automated messaging flow that starts after players finish your Welcome Journey. Its goal is to reward continued play, move players through loyalty tiers and turn retained players into high value advocates. This tutorial covers two implementation cases:

• Case 1 – Basic: Session count and two tags (loyalty_tier, lifetime_points) set via the OneSignal SDK or API. Fixed milestone rewards. No webhooks.
• Case 2 – Advanced: Same linear tier progression structure as Case 1. Adds webhooks that sync to your backend, tier-locked monetization offers, deeper Liquid personalization and a winback email escalation for players inactive 14+ days.

You can start with Case 1 and graduate to Case 2 once your data infrastructure is in place. Both cases are designed to begin after a player completes your Welcome Journey (typically Day 7+).

---

​

Loyalty program goals

---

​

Prerequisites

For both cases:

• Familiarity with Journeys overview concepts
• An active OneSignal app with push notifications configured
• OneSignal mobile SDK installed
• Players have completed your onboarding flow (7+ sessions recommended)

For Case 1, you also need:

• Segment: Session count > 6 (players who have completed onboarding)
• Tags loyalty_tier and lifetime_points set on the player’s profile via the mobile SDK addTags method or the Update user API endpoint

For Case 2, you also need:

• External ID configured so player profiles are unified across devices and channels
• Data tags representing loyalty state, purchase history and engagement metrics
• Custom events firing from your game backend for purchases, level-ups, daily logins, social actions and milestone completions
• Journey webhooks enabled on your account (contact OneSignal sales for access)

---

​

Loyalty tier structure

Both journeys use a four tier system. The thresholds and perks below are examples. Define what makes sense for your game’s economy. Your game backend calculates and stores the official point total. The journey reads that value through tags to route players and personalize messages.

---

​

Case 1: Basic loyalty journey

Target players using session count and two tags set on each player’s profile via the OneSignal SDK or API. This case requires no custom event tracking and can run alongside your existing onboarding journey.

​

How this journey works

The journey rewards players who completed onboarding by recognizing their progress through Bronze → Silver → Gold → Platinum and bringing them back if they go quiet. After session 6 the player enters the journey at Bronze and sees a welcome in-app message. The journey then runs three nearly identical tier sections in order: Bronze → Silver, Silver → Gold, Gold → Platinum. Each section watches three signals in parallel and routes the player down whichever fires first:

• Approaching the next tier: send a points-to-go push, then wait for the tier to be reached
• Already in the next tier (catch-up): skip the push and go straight to the celebration in-app message
• Inactive for 7+ days: send a re-engagement push, then wait for the tier to be reached

When the player reaches the next tier, all branches converge at a celebration in-app message. The pattern repeats for the next section. After the Platinum celebration, the journey ends with a referral push. This case doesn’t require custom events or backend webhooks. Your app or backend updates the loyalty_tier and lifetime_points tags via the OneSignal SDK (addTags) or server-side API and the journey reacts to segment membership changes automatically.

​

At a glance

​

Journey settings

Configure these settings on the Settings tab of the journey before building the steps. See Journey settings for full reference.

​

Required segments

Wait Until conditions route players based on segment membership. Create these segments before building this journey.

​

Journey steps

The journey opens with a welcome in-app message, then runs three tier sections in order: Bronze → Silver, Silver → Gold and Gold → Platinum. Each tier section is self-contained and ends at its tier celebration in-app message. Each tier section opens with a multi-condition Wait Until that forks into four branches. Build the nodes for each branch separately in the journey builder. All non-exit branches converge at the tier celebration in-app message before the next tier section begins. Each Wait Until’s expiration branch exits the journey if the player doesn’t progress: 21 days at the start of each tier section, 10 days after each push. The journey settings disable re-entry, so route stalled players to a separate winback journey.

​

Welcome (before the first tier section)

​

Tier section: Bronze → Silver

The fork: multi-condition Wait Until

Branch 1: Bronze approaching Silver

Build these nodes on the Bronze approaching Silver branch coming out of the fork.

Branch 2: Silver tier (catch-up)

For players who reach Silver in one jump and skip the approaching segment. For example, a player who earns 500 points in a single burst (a big purchase or daily reward bundle) and crosses straight from Bronze into Silver. Don’t add any nodes on this branch. Connect it directly to the Silver tier celebration in-app message in the convergence section below.

Branch 3: Low weekly engagement

Build these nodes on the Low weekly engagement branch coming out of the fork.

Convergence: Silver tier celebration IAM

All non-exit branches reach this node. After the celebration in-app message, continue to the next tier section.

​

Tier section: Silver → Gold

The fork: multi-condition Wait Until

Branch 1: Silver approaching Gold

Build these nodes on the Silver approaching Gold branch.

Branch 2: Gold tier (catch-up)

For players who reach Gold in one jump and skip the approaching segment. Don’t add any nodes on this branch. Connect it directly to the Gold tier celebration in-app message in the convergence section below.

Branch 3: Low weekly engagement

Build these nodes on the Low weekly engagement branch.

Convergence: Gold tier celebration IAM

All non-exit branches reach this node.

​

Tier section: Gold → Platinum

The fork: multi-condition Wait Until

Branch 1: Gold approaching Platinum

Build these nodes on the Gold approaching Platinum branch.

Branch 2: Platinum tier (catch-up)

For players who reach Platinum in one jump and skip the approaching segment. Don’t add any nodes on this branch. Connect it directly to the Platinum tier celebration in-app message in the convergence section below.

Branch 3: Low weekly engagement

Build these nodes on the Low weekly engagement branch.

Convergence: Platinum tier celebration IAM and referral

All non-exit branches reach these nodes. The journey ends here. Move Platinum players into a separate VIP journey for ongoing perks and event invitations.

​

Success metrics to track

• Tier progression rate (% of players reaching Silver within 30 days)
• Push CTR on tier approaching notifications
• Re-engagement rate after a Low weekly engagement push
• Platinum conversion rate

​

Best practices for Case 1

• Introduce the loyalty program with a clear visual. An in-app message with a tier map shows players the full progression path and what they earn at each tier. Players are more likely to engage when they know what they’re working toward.
• Let players progress at their own pace. Wait Until on segment entry reacts the moment a player crosses a threshold or lapses, so messages land when they’re relevant instead of on a fixed weekly check. Players who never trigger a condition exit cleanly at the Wait Until expiration.
• Celebrate every tier transition in-app. Push notifications announce proximity; in-app messages celebrate achievement. The tier up moment should feel like unlocking a new level in the game itself.
• Move Platinum players into a separate VIP journey. The Loyalty Journey’s job ends at Platinum. Once a player hits that tier, move them into a separate journey focused on VIP perks, exclusive events and referral programs.

​

Add more channels and message types

Push is the backbone of Case 1, but adding a second channel gives you coverage when push is disabled and richer moments inside the game.

• Add email as a backup channel for inactivity. Some players disable push or never grant permission. Place an Email step after the Low weekly engagement push so every inactive player receives the message in at least one channel. The email can carry a tier progress summary with a visual progress bar and a comeback incentive. Push delivers only to subscribed push subscriptions; email reaches everyone with an email subscription.
• Use in-app messages to deepen tier celebrations. When an approaching push opens the app, the next session is a high intent moment to surface a full celebration with a rich in-app message. Place the in-app message step after the corresponding push so it triggers on the session the player opens in response.

---

​

Case 2: Advanced loyalty journey

Same linear tier progression structure as Case 1. Adds webhooks that sync to your backend, tier-locked monetization offers, deeper Liquid personalization and a winback email escalation for players inactive 14+ days.

​

How this journey works

Same Bronze → Silver → Gold → Platinum structure as Case 1, plus an enrollment phase up front and richer follow-ups after each tier. After session 6 the player enters at Bronze, sees a personalized welcome in-app message and is initialized via a Tag User node before the tier sections begin. The journey then runs three tier sections. Each section watches three signals in parallel:

• Approaching the next tier: send a points-to-go push, then wait for the tier to be reached
• Already in the next tier (catch-up): skip the push and go straight to the celebration in-app message
• Inactive for 7+ days: send a re-engagement push. If the player is still inactive at 14 days, escalate to a winback email.

When the player reaches the next tier, all branches converge at a celebration in-app message followed by a webhook to your backend to activate perks. Silver adds a guild prompt for unaffiliated players, Gold adds a tier-locked offer split for buyers vs. non-buyers and Platinum ends with a graduation tag, referral push and Ambassador recognition for players with 3+ referrals. This case requires custom events, backend webhooks and richer player data. Your backend keeps tags up to date via the OneSignal SDK or API; the journey fires webhooks back to activate perks on each tier transition.

​

At a glance

​

Journey settings

Configure these settings on the Settings tab of the journey before building the steps. See Journey settings for full reference.

​

Required data

Set the following user properties and events via SDK calls or the server-side API.

​

User properties (tags)

​

Events to track

These events power backend logic that updates the tags above. The journey itself reacts to segment entry (which the tag updates trigger) rather than to events directly.

​

Required segments

Wait Until and Yes/No Branch nodes route players based on segment membership. Create these segments before building this journey.

​

Journey map

This journey runs as a single linear flow: an enrollment chain at the top, three tier sections (Bronze → Silver, Silver → Gold, Gold → Platinum) that follow the same shape as Case 1 and a Platinum finale. Each tier section adds a webhook to sync perks to your backend along with tier-locked monetization or social prompts.

​

Phase 1: Loyalty program enrollment

​

Phase 2: Bronze → Silver progression

This phase mirrors Case 1’s tier section pattern, enriched with a webhook to activate Silver perks on your backend and a guild prompt for unaffiliated players. The phase opens with a multi-condition Wait Until that forks into four branches. Build the nodes for each branch separately in the journey builder. All non-exit branches converge at the Silver tier celebration in-app message.

The fork: multi-condition Wait Until

Branch 1: Bronze approaching Silver

Build these nodes on the Bronze approaching Silver branch coming out of the fork.

Branch 2: Silver tier (catch-up)

For players who reach Silver in one jump and skip the approaching segment. For example, a player who earns 500 points in a single burst (a big purchase or daily reward bundle) and crosses straight from Bronze into Silver. Don’t add any nodes on this branch. Connect it directly to the Silver tier celebration in-app message in the convergence section below.

Branch 3: 7-day inactive

Build these nodes on the 7-day inactive branch coming out of the fork. On the 14-day sub-branch of the Wait Until above:

Convergence: Silver tier celebration IAM and follow-ups

All non-exit branches reach these nodes.

​

Phase 3: Silver → Gold progression

Same shape as Phase 2 with Silver to Gold segments, plus a tier-locked monetization offer after the Gold celebration in-app message.

The fork: multi-condition Wait Until

Branch 1: Silver approaching Gold

Build these nodes on the Silver approaching Gold branch coming out of the fork.

Branch 2: Gold tier (catch-up)

For players who reach Gold in one jump and skip the approaching segment. Don’t add any nodes on this branch. Connect it directly to the Gold tier celebration in-app message in the convergence section below.

Branch 3: 7-day inactive

Build these nodes on the 7-day inactive branch coming out of the fork. On the 14-day sub-branch of the Wait Until above:

Convergence: Gold tier celebration IAM and follow-ups

All non-exit branches reach these nodes.

​

Phase 4: Gold → Platinum progression and Platinum finale

Same shape as Phase 3 with Gold to Platinum segments. Ends with a Platinum referral push and Ambassador recognition for high referral players.

The fork: multi-condition Wait Until

Branch 1: Gold approaching Platinum

Build these nodes on the Gold approaching Platinum branch coming out of the fork.

Branch 2: Platinum tier (catch-up)

For players who reach Platinum in one jump and skip the approaching segment. Don’t add any nodes on this branch. Connect it directly to the Platinum tier celebration in-app message in the convergence section below.

Branch 3: 7-day inactive

Build these nodes on the 7-day inactive branch coming out of the fork. On the 14-day sub-branch of the Wait Until above:

Convergence: Platinum celebration IAM, VIP handoff and referral

All non-exit branches reach these nodes. The journey ends after the Ambassador check.

​

Handling tier decay

If your loyalty program includes tier decay, handle it with care:

1. Warning push (7 days before deadline): “Your {{ loyalty_tier | capitalize }} status expires in 7 days. Bank {{ points_needed }} more points this month to keep your perks.”
2. Grace period (3 days): Give a 3-day grace period before downgrading. Send a final push: “Last chance. Your {{ loyalty_tier | capitalize }} perks expire tomorrow. Log in to save your tier.”
3. Downgrade with dignity: “Your tier has been adjusted to {{ new_tier | capitalize }}. Progress isn’t lost. Earn {{ points_to_restore }} points to restore your {{ old_tier | capitalize }} status.”

​

Success metrics to track

• Average days to reach each tier
• Re-engagement rate after 7-day inactivity push
• First purchase rate at Gold tier
• Winback email conversion rate at 14-day inactivity
• Referral conversion rate from Platinum players

​

Best practices for Case 2

• Add a Webhook after every tier celebration in-app message. OneSignal doesn’t unlock perks. Your game does. A Webhook step notifies your game server the moment a player reaches a new tier, so their rewards activate right away instead of waiting for the next sync.
• Lock offers to specific tiers. A Gold only deal converts better than a random promotion because players perceive it as earned. Non-buyers at Gold need a reason to make their first purchase; existing buyers need a value upgrade.
• Handle tier decay with empathy. Warn early, offer a grace period and frame any downgrade as temporary. A “highest tier achieved” badge preserves the player’s sense of accomplishment even during inactive periods.
• Celebrate every tier transition in-app. The tier up moment should feel like unlocking a new level in the game itself. Push announces proximity; the in-app message delivers the reward.
• Hand off Platinum graduates to a VIP journey. This journey ends at Platinum. Tag Platinum players on the way out and use that tag as the entry segment for a separate VIP journey focused on exclusive events, beta invitations and referral programs.

​

Add more channels and message types

The rich data in Case 2 makes it possible to expand beyond push and in-app messages and add channel moments tied to specific player behavior.

• Add SMS for high value moments. Once a player crosses a value threshold like first purchase or Platinum tier, SMS becomes a high attention channel for time sensitive offers: a limited time event invite, a flash sale on a class matched pack, or an exclusive Platinum drop. Reserve SMS for VIP tier audiences to keep send volume low and engagement high.
• Extend email beyond winback. Email isn’t only a re-engagement fallback. Use Email steps after tier celebration in-app messages and on a recurring schedule (Days 30, 60, 90 of loyalty program membership). Deliver class specific tips, loyalty program recaps and exclusive member content for players who prefer less frequent in-app messaging.
• Layer on a separate event-driven journey for limited time events. Use the event_participation event as the entry trigger for a dedicated event-driven journey that recognizes participation, rewards points and gates exclusive challenges to Gold and Platinum players. Keeping it separate avoids tangling event responses into the linear tier flow.

---

​

Case 1 vs. Case 2 at a glance

---

​

Getting started

Start with Case 1 if you’re setting up a loyalty program for the first time. It goes live with minimal setup and covers the core tier progression window without requiring event instrumentation or backend webhooks. As your data infrastructure matures, layer in Case 2 elements progressively. You don’t need all 10 tags and 7 events on day one. Even adding webhooks to sync Silver, Gold and Platinum perks to your backend meaningfully strengthens the loyalty experience. The Loyalty Journey picks up where the Welcome Journey ends. By Day 7+ players have established a habit. From there the journey rewards that habit, moves players through tiers and turns the most engaged into advocates.

---

​

Track performance