> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zbdpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Player Communication Guide
> What to say to players at each stage of their rewards journey — and the one principle that makes all of it work.
Getting the integration right technically is half the job. How you introduce and talk about rewards determines whether players engage, claim, build a daily habit, and tell their friends. This page is for game designers and marketing — the people writing copy, designing flows, and sending notifications.
## What makes rewards convert
**Three things drive conversion. If one of them is missing, your rewards are likely to underperform:**
1. Your UI/UX **shows and explains** how rewards work and how to claim them
2. You're **rewarding enough** to be worth coming back for
3. You **know your audience** — acquiring players who want to earn improves conversion
Most integrations that underperform are missing one of these three — not a copy problem.
### 1. Show and explain how rewards work
Players won't claim what they don't understand. Use every surface you have, not just one:
* **Native game elements** do the most work, because they're always present: a persistent balance counter alongside your other currencies, reward toasts at the moment of earning, and a progress bar toward the next reward. Build these into your own UI — don't rely on the ZBD modal to carry the message.
* **[Creatives](/embedded-rewards/creatives)** handle the set-piece moments: the reveal after the first reward lands, and milestone nudges. Dashboard-configured, in your art style, changeable without an app release.
* **[Local notifications](/embedded-rewards/local-notifications)** (or your own push stack) bring players back when they have something unclaimed.
Two specifics that matter most: **give the first reward early**, within the first minutes of normal play, so players discover a balance that already exists rather than a counter at zero; and **show progress toward a near, named reward** — [`GetGiftCards`](/embedded-rewards/gift-cards) gives you the percentage for exactly that.
### 2. Reward enough to be worth it
Nobody changes their behavior for a few cents. If a player's realistic earnings are trivial, no amount of good UX will produce engagement — and they'll tell other players it isn't worth it.
The way to fund meaningful rewards without hurting your margin is to size them off actual revenue rather than a flat guess:
* **Connect your MMP.** When an ad impression or completed view is confirmed, raise that player's withdrawal limit so players who generate more can earn more. This is the highest-leverage change you can make here, and there are options that work without a backend. See [Increasing Limits with MMP Data](/embedded-rewards/mmp-postbacks).
* **Start from a revenue share, not a fixed amount.** 10–20% of ad-generated revenue is the usual starting range. See [Reward Economics](/embedded-rewards/reward-economics) for recommended values.
### 3. Know your audience
Acquisition shapes the ceiling on everything else here. UA aimed at players who want to earn — or who'd be interested in earning — will improve your conversion rates: rewarded-play audiences, earning-focused creatives and channels, messaging that mentions real rewards.
It's worth being deliberate about it. Players who arrive with no interest in earning are harder to convert, so the same rewards UX will read very differently depending on who you brought in.
The rest of this page is the detail behind point 1: the principle all reward copy follows, then what to say at each moment.
## The one principle: reveal, don't offer
Players installed your game to play, not to earn. A rewards pitch they haven't earned anything from yet is a cold offer — and cold offers trigger suspicion, not desire. An unexplained reward reads as a hidden cost: *what's the catch?*
So don't *offer* rewards. **Reveal them.** The player should discover they've already earned something by doing the thing they came to do. Every screen and sentence should reinforce: this is part of the game you already like, it's already working, and here's why it's real.
Two rules follow from this:
1. **Never show a zero balance as the player's first exposure.** Fire the first reward within the first minutes of normal play, so by the time the player notices the counter, something is already in it. "You've already earned 240 coins" converts; "Start earning!" doesn't.
2. **Always pair the reward with the honest reason.** An unexplained reward feels like a scam. One sentence kills the suspicion:
**The reason line — the single highest-leverage sentence in your rewards copy:**
*"Game studios share their ad revenue with players. The more you play, the more you earn."*
The modal's built-in first-time screen doesn't carry this line, so ship it yourself: a [first-open creative](/embedded-rewards/creatives) is the ideal vehicle — it shows in your game's art style and you can update it without an app release. Never present the reward without the reason.
## Core principles
**Speak in your game's voice, and keep ZBD invisible until it adds credibility.** The player trusts the game they chose to install; the rewards layer should inherit that trust, not spend it. Your fonts, your art, your currency, your tone. ZBD appears at the payout step, where a real payment processor makes the money credible — never in headers or gameplay copy.
**Pair your currency with its real-money value.** Lead with your themed currency — it keeps rewards native to your game and lets you be generous with the numbers — and show the dollar value alongside it: players are ultimately motivated by real money. "You earned 2,500 coins (\$0.25)" gives them both. Concrete dollar milestones remain your strongest motivator: *"Next reward: \$5 gift card — 80% there."*
**Show progress to the *next* milestone, never a far summit.** A close goal accelerates play; a distant one demotivates. [`GetGiftCards`](/embedded-rewards/gift-cards) gives you `unlockedPercent` for exactly this — bind it to a progress bar toward a named, concrete reward.
**Say "claim", not banking verbs, at first touch.** "Claim your reward" feels like winning; "withdraw" and "cash out" feel like banking, and banking feels like risk. Reserve cash-out vocabulary for the payout flow itself. (The modal's built-in CTA currently reads "Cash Out" — that copy is fixed product UI inside the claim flow; the vocabulary *you* control on the way there should say claim.)
**Send players to the modal when there's something worth claiming.** The modal opens on their balance and cashout options, so it lands best once there's a balance worth acting on — a player sent there with nothing to claim just sees an empty wallet. Never gate the value reveal behind sign-up: players don't need any account to see what they've earned.
## The journey, in five moments
| Moment | What happens | Your tool |
| - | - | - |
| **Earn** | "+40 coins" as ambient feedback while playing — noticed, not interrupting. Tie triggers to high-emotion gameplay moments. | Your game UI + `SendReward` |
| **Reveal** | One screen, after the first reward has landed: the balance they already have, the reason line, one CTA ("Keep playing"). | A [creative](/embedded-rewards/creatives) |
| **Progress** | Balance always visible; progress bar toward the next named reward. | Your game UI + [`GetGiftCards`](/embedded-rewards/gift-cards) |
| **Claim** | Player taps through with a balance worth claiming, picks a payout option, and celebrates like a level-up, not a receipt. | The ZBD modal (`ShowModal`) |
| **Return** | Milestone reminders while away; tomorrow's fresh earning allowance framed as an opportunity. | [Local notifications](/embedded-rewards/local-notifications) + creatives |
## Communication touchpoints
| Touchpoint | When | Goal | Sample copy |
| - | - | - | - |
| First reward | First reward event, session 1 | Make it feel real, ambiently | "+500 \[Currency]" toast — no modal, no interruption |
| Reveal | Right after the first reward | Pair value with the reason | "You've already earned 500 \[Currency] (\$0.05). This game shares its ad revenue with players — the more you play, the more you earn." |
| Progress milestone | Meaningful % toward a reward | Keep the next goal near | "You're 80% of the way to a \$5 gift card." |
| First claim | Balance worth claiming | Convert | "Your first reward is ready to claim." |
| Limit reached | Player has withdrawn all their limit currently allows | Turn a ceiling into retention | "You've maxed out today's rewards. Come back tomorrow to earn more." |
| Re-engagement | Lapsed player (3+ days) | Re-activation | "Your \[X] \[Currency] are still waiting — come and claim them." |
## Withdrawal limit messaging
The daily earning allowance is your most powerful retention mechanic — use it that way.
When a player has withdrawn everything their limit currently allows, the message is: **"Come back tomorrow to earn more."** Not "You've reached your limit." Not "Withdrawal limit: \$0.20." Their allowance to unlock more resets every 24 hours — frame that as tomorrow's opportunity, not today's restriction.
## Push notifications
Same copy model as [local notifications](/embedded-rewards/local-notifications) — concrete goal over bare number, claim over cash out:
| Scenario | Sample copy |
| - | - |
| Unclaimed rewards | "You've got \[X] \[Currency] waiting — come and claim them." |
| Near a milestone | "You're \[X]% of the way to a \[card] gift card. Keep playing to unlock it." |
| Reward ready | "You've unlocked a \[card] gift card — come and claim it." |
| New day, fresh allowance | "You can earn more rewards today. Time to play." |
| Day 7 streak milestone | "7-day streak! A special reward is in your daily chest." |
No urgency theater ("Limited time! Act now!") — urgency reads as manipulation to someone who didn't come to shop.
## In-app messages
| Scenario | Sample copy |
| - | - |
| Rewards feature launch (existing players) | After their next reward lands: "You've already earned \[X] \[Currency] — \[Game Name] now shares its ad revenue with players. Keep playing to unlock real rewards." |
| Post-first-reward | "You just earned your first \[Currency]! \[X] more and your first reward is ready to claim." |
| Approaching a milestone | "Almost there — \[X] \[Currency] until your \$5 gift card." |
| After a long session | "Great session! You earned \[X] \[Currency] today. Keep playing tomorrow for bonus rewards." |
Avoid full-screen takeovers at launch — a pitch before play is a cold offer. Let the first reward land, then reveal.
## Say this, not that
| Avoid | Say instead | Why |
| - | - | - |
| "Earn real money!" | "Your playtime just paid out" / "You've already earned \[X] \[Currency]" | Ad-speak triggers skepticism; already-happened is a fact |
| "Withdraw" / "Cash out" (first touch) | "Claim your reward" | Banking verbs feel like risk; claiming feels like winning |
| "Sats", "Bitcoin", "wallet", "Lightning" | "Your rewards" | Crypto vocabulary spooks a casual audience — keep it behind the payout-methods door (Bitcoin-native games excepted) |
| "Sign up to start earning" | "You've already earned \[X] \[Currency]" | Never gate the value reveal behind effort |
| A far-off summit ("Save up for a \$100 payout") | "Next reward: \$5 gift card — 80% there" | Near milestones motivate; distant goals demotivate |
| "Limited time! Act now!" | "New bonus round on your next game" | Urgency reads as manipulation |
| "ZBD Rewards" as a header | "\[Game]'s Reward Vault" (or Loot, Treasury…), "powered by ZBD" small at the payout step | A third-party brand is a context switch |
| "You earned 1,200 \[Currency]" (value hidden) | "You earned 1,200 \[Currency] (\$0.12)" | Players are motivated by real money — show the value with the currency |
| "Rewards unavailable" (player hasn't earned) | Hide rewards UI silently | Nothing to miss, nothing to explain |
| "ZBD is down" | "Rewards are temporarily unavailable" (players with a balance only) | Never name the platform; never alarm players who haven't started |
Tone throughout: the voice of the *game*, not of a fintech. Short, warm, second person, zero exclamation-mark salesmanship. One idea per screen.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.