gamemantra.aigamemantra.ai|Developer Docs
Reference

Player Segments

Not all players are the same. A player who has never spent money needs a completely different offer than someone who spends every week. gamemantra.ai automatically classifies every player into a segment — no setup required.

How it works: The AI runs every 4 hours, reads each player's session data and purchase history, and assigns them a segment. Offers are then matched to templates designed for that exact segment. The AI also updates immediately when a player makes their first purchase — no waiting 4 hours for that critical moment.

Lifecycle Segments — how far along in the relationship

These are the primary segments. Every player has exactly one lifecycle segment at any point in time.

🌱
New Playernew

Classified when: First 48 hours since install, never spent money

Best offer: Starter pack ($0.49–$0.99). This is the onboarding window. Keep it cheap, make it feel like a gift.

~15% of DAU
💙
Never Purchasednever_purchasedNew

Classified when: Older than 48h, still playing, spend score = 0, has NEVER made any IAP

Best offer: First purchase offer ($0.49 one-time). These players choose to be free — you need a very low barrier and strong value. One-time-only badge helps.

~30–50% of DAU
🎮
Active Freeactive

Classified when: 2+ sessions in last 7 days, spend score = 0 (may have purchased before but very long ago)

Best offer: Engagement bundles ($1.99–$3.99). They're invested in the game. Show value, not just price.

~20–35% of DAU
💳
Payingpaying

Classified when: Has made at least 1 IAP in the last 60 days

Best offer: Bundle upgrades ($2.99–$9.99). They've proven they'll spend. Show bigger value, premium items.

~5–10% of DAU
🐳
Top Spenderwhale

Classified when: Spend score ≥ 0.7 (top spenders — roughly top 1–5% by revenue)

Best offer: Exclusive bundles ($9.99–$49.99). Unique items, legendary gear, exclusive cosmetics. Price is not the barrier.

~1–2% of DAU, 40–60% of revenue
⚠️
At Riskat_risk

Classified when: Had activity before (was active/paying/new) but zero sessions in last 7 days

Best offer: Re-engagement discount ($0.99–$2.99). They know the game. Remind them what they're missing. Time-limited urgency helps.

~10–20% of total players
🔄
Returningreturning

Classified when: Was at_risk last check, now has at least 1 session this week

Best offer: Welcome-back bundle ($1.99–$4.99). They came back themselves — they're motivated. Don't undersell.

~3–8% of DAU
🔴
StuckstuckNew

Classified when: Failed the same level 3 or more consecutive times

Best offer: Level-specific help ($0.99–$2.99). This is the highest-urgency moment in the game. They want to pass the level right now. 'We know this is hard — here's a hand' framing works best.

~5–15% of active players at any time

Progression Stage — where they are in the game

This is a parallel dimension written alongside the lifecycle segment. An early_game whale (spends big in first week) and a late_game whale (veteran big spender) want completely different offers. Offer templates can target combinations of both.

Early Game
First 7 days
Onboarding packs, low-commitment items, tutorials + gear
Mid Game
7–60 days active
Bundle deals, XP boosters, seasonal content access
Late Game
60–180 days active
End-game currency, exclusive cosmetics, prestige items
Endgame
180+ days active
Cosmetics-only or prestige content — they've seen everything

Combining Segments for Precision

The AI can match offer templates that target two dimensions at once: lifecycle + event. The more specific a template is, the higher its priority.

SegmentTrigger eventPriorityWhy this combination works
never_purchasedlevel_fail_near_miss10+First-time buyer + frustration = highest first-IAP conversion. $0.49 is the right price.
whaleboss_raid (RPG)10+Top spender about to face hardest content = maximum willingness to pay.
stuckhard_level_fail (Match-3)10+Repeated failure + specific obstacle = player knows exactly what they need.
at_risksession_start10+They came back after 7+ days — they're reconsidering the game. This is your re-monetization window.
never_purchased(any)3Generic first-purchase offer as a fallback — shows on any trigger.
returning(any)3Welcome-back deal fires on any trigger — always relevant for returnees.

How to see your players' segments

Dashboard → Analytics → Player Segments

Bar chart showing distribution of all 8 lifecycle segments for your game. Updated every 4 hours. See how many players are at risk, how many have never purchased, and track changes over time.

Dashboard → Offers → Shadow Mode

In shadow mode, every AI offer decision is logged with the player's segment, event, offer template selected, and why. Use this to verify that segments are matching the right templates before going live.

Common Questions

Can a player be in multiple segments at once?
Each player has one primary lifecycle segment (new/active/paying/whale/at_risk/returning/stuck/never_purchased). But the progression stage (early_game/mid_game/etc.) is separate — so a player can be 'paying + mid_game' and your templates can target that combination.
What if I don't have offer templates for a segment?
The AI falls back to less specific templates: first it tries event+segment match (priority 10+), then event-only (priority 5), then segment-only (priority 3), then generic for your genre (priority 0). You'll always get an offer as long as you have generic genre templates.
My game has no lives system — what's lives_depleted for me?
Enable only the events that apply to your game. If you have no lives system, just don't enable lives_depleted in your offer trigger rules. The AI won't show offers for events you haven't enabled.
How quickly does the segment update when a player buys?
Immediately for purchase events. When your SDK fires an iap_purchase event, the platform fast-paths the player to 'paying' segment in Redis within 1–2 seconds. The 4-hour Celery batch only handles the full recalculation.