@indiegems/gem-web-sdk 8.1.0 → 9.1.0

package/docs/rewarded-ads.md

@@ -0,0 +1,616 @@
+# Rewarded ads
+
+A rewarded placement is a button your player presses for something your game gives, such as a
+revive or three extra dice rolls. The button says it is an ad and names the reward: "Watch an ad
+for 3 dice rolls". Pressing it is the player's choice to watch, so the Arcade starts the ad
+straight away, labelled as an ad, with no prompt of its own first. The platform then decides
+whether the player is rewarded, and writes the reward into **your game's own inventory** for that
+player. Your game never grants the reward, and never learns from the answer whether one was
+granted. It reads its inventory.
+
+```js
+watchAdButton.addEventListener('click', async () => {
+  // First, inside the click: the press is what lets the ad start.
+  await gem.ads.requestAd({ placement: 'dice_rolls', format: 'rewarded' });
+  gem.me.inventory.refresh(); // drop what is cached
+  const snap = await gem.me.inventory.snapshot(); // a reward granted before the answer is here
+});
+```
+
+That is the whole of the asking. What makes it pay is four things you set up once:
+
+1. **A reward**: an item or currency of your own that the player keeps (§1).
+2. **A placement** in your game config. It says what one press grants, how long the ad plays, how
+   often it can pay, and what a press gets when no ad plays (§2).
+3. **A spend**: the recipe your game runs when the player uses the reward (§4).
+4. **A button** that says it is an ad, names the reward, and is drawn only when it can pay (§5).
+
+The same asking and spending code runs whether the Arcade plays a test ad, grants the reward with no
+ad, or plays a real one (§8), and moving between those needs no new SDK version and no config
+change.
+
+## 1. The reward is your own, and the player keeps it
+
+A reward is one to four grants of **your game's own** items or currencies, up to 100 of each (a
+platform currency only as below). It must be something the player keeps and cannot pass on, and
+the upload refuses a config where it is not:
+
+- **Soulbound.** Every item or currency it grants has `transfer_policy: none`. A reward cannot be
+  traded, gifted or moved.
+- **An ordinary item or a currency.** Not a bundle, not a loot box, and not a progression.
+- **A platform currency only where the platform lists it.** The upload refuses a reward that
+  names a platform currency unless `gemctl platform config` lists that currency, for your game, as
+  grantable by `rewarded`.
+- **Never convertible into one of those.** The upload follows every recipe and catalog entry that
+  spends the reward, then everything that spends what those grant, and so on. If that chain reaches
+  anything transferable, a platform currency `gemctl platform config` does not list as grantable by
+  `rewarded`, a bundle, a loot box, or a progression that fires a platform grant, the upload is
+  refused, and the finding names the path from the reward to the thing it reached.
+- **Never spent on a loot draw.** Neither the reward nor anything it converts into may be a cost
+  of a recipe that rolls a loot table, so "spend a token to spin the wheel" is refused too.
+- **A plain `display_name`.** It is the reward's name wherever the Arcade shows it in its own
+  chrome, so a name with markup or invisible characters is refused.
+
+And three things the upload warns about rather than refuses:
+
+- **Keep `client_writable: false` on the reward.** If your game's client may write it, a modified
+  client can grant itself one without an ad, and the placement is decoration.
+- **Prefer a reward that is not also sold for a platform currency.** A reward counts as sold for
+  one when it carries a platform price itself, when a recipe priced in a platform currency grants
+  it, or when anything it converts into (the chain above) is sold either way. Such a placement is
+  allowed, with a warning, but it must say `without_ads: nothing` (§2) — the upload refuses one
+  that says `grant` — and outside test ads it is only ever served behind an ad whose completion
+  the platform verifies with the ad provider.
+- **Keep its `display_name` to 40 characters or fewer.** The Arcade cuts a longer one short where
+  it shows it.
+
+For a revive, the reward is a single-use token:
+
+```yaml
+items:
+  - id: '<uuid>'
+    slug: revive_token
+    item_type: item
+    display_name: 'Revive token' # the reward's name in the Arcade's own chrome
+    fungible: true
+    stack_size: 1
+    consumable: true
+    transfer_policy: none # a reward is never transferable
+    client_writable: false # or a modified client can grant itself one
+```
+
+`gemctl config schema` is the authoritative field list for all of this, and for §2 and §4.
+
+## 2. Declare the placement in your game config
+
+Each placement your game asks for is one entry in the `rewarded_placements` section, keyed by the
+same string your game passes as `placement`:
+
+```yaml
+rewarded_placements:
+  - placement: classic_revive # exactly the string your game passes
+    grants:
+      - { type: item_grant, item_definition_slug: revive_token, quantity: 1 }
+    max_per_day: 5 # optional: leave it out for no daily cap
+    max_held: 1 # no grant while the player already holds one
+    without_ads: grant # required: what a press gets when no ad plays
+  - placement: daily_drop_extra
+    grants:
+      - { type: item_grant, item_definition_slug: daily_drop_attempt, quantity: 1 }
+    min_watch_secs: 15 # optional: leave it out for the platform's default, 5 seconds
+    max_per_day: 2
+    max_held: 1
+    without_ads: grant
+```
+
+| field                     | what it says                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `placement`               | The name your game passes. 1 to 32 characters of `a-z`, `0-9`, `-` and `_`, unique in the document. At most 16 placements per game.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `grants`                  | 1 to 4 `item_grant` or `currency_grant` operations on your own items and currencies (§1). A `currency_grant` takes a `currency_slug` and an `amount`; an `item_grant` takes an `item_definition_slug` and a `quantity`.                                                                                                                                                                                                                                                                                                                                                       |
+| `min_watch_secs`          | How long the ad plays before the press pays, in whole seconds, 1 to 150. The ceiling is there because the SDK settles a rewarded ask after 180 seconds and the Arcade gives up on an ad still open at 170 seconds; an ad still open then is a skip and pays nothing. **Optional**: leave it out and the platform's default applies, which is 5 seconds unless the platform sets another. A test ad that closes sooner pays nothing. A real ad provider decides for itself when its ad has finished, so for a real ad this is the length the Arcade asks for, not a rule (§8). |
+| `max_per_day`             | Grants per player per UTC day. **Optional**: leave it out and the placement has no daily cap (§6).                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `cooldown_seconds`        | Seconds between two grants to one player, 0 to 86400. Defaults to 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `max_held`                | No grant while the player already holds at least this many of the granted item. 1 to 100, and only on a placement whose grants are all items.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `without_ads`             | **Required, with no default:** `grant` or `nothing`. What a press gets when no ad plays: where no ad serves your channel at all, and where one does but no ad was available for this press or it failed to play (§8).                                                                                                                                                                                                                                                                                                                                                         |
+| `allowance_currency_slug` | Optional: one of your own currencies that each grant also spends 1 of. Use it when another path in your game must share the same daily cap. It must not be `client_writable`, must have `transfer_policy: none`, and needs a bucket that resets (daily, say) or it never refills.                                                                                                                                                                                                                                                                                             |
+
+The placement only **selects** a reward your own config declared. Your game sends no reward, no
+amount, no watch time and no item in the request — nothing from your frame is trusted for that — so
+a modified client can ask for a declared placement and nothing else.
+
+Ship it the way every config section ships: upload, then promote to a channel. A channel serves
+the placements in the config version promoted to it, and a reward can be retuned, its watch time
+changed, or `without_ads` flipped, with a new upload and a promote, with no new build.
+
+⚠️ **Check that `gemctl config schema` lists `rewarded_placements` before you rely on it.** The
+upload drops a top-level section the backend does not know without a word, so a placement uploaded
+where the schema does not list it does nothing at all. The same goes for `min_watch_secs`: if the
+schema does not list it, the placement plays for the platform's default.
+
+### More for watching longer: two placements
+
+To pay more for a longer ad, declare **two placements**, each with its own watch time, reward and
+caps, and draw two buttons:
+
+```yaml
+rewarded_placements:
+  - placement: dice_rolls_short
+    grants:
+      - { type: item_grant, item_definition_slug: bonus_roll, quantity: 1 }
+    min_watch_secs: 5
+    max_per_day: 10
+    without_ads: grant
+  - placement: dice_rolls_full
+    grants:
+      - { type: item_grant, item_definition_slug: bonus_roll, quantity: 3 }
+    min_watch_secs: 30
+    max_per_day: 3
+    without_ads: nothing # see below
+```
+
+"Watch a short ad for 1 dice roll" asks for `dice_rolls_short`. "Watch a full ad for 3 dice rolls"
+asks for `dice_rolls_full`. There is no partial payout: a player who closes the full ad after ten
+seconds has skipped it and gets nothing, not the short reward.
+
+Choose `without_ads` for each placement on its own. Where no ad plays (§8), a `grant` placement
+pays without one. If both said `grant`, the bigger reward would cost the player nothing extra, and
+everyone would press that button. `nothing` on the bigger one keeps it a reward for watching.
+
+## 3. Ask from the press, then re-read
+
+```js
+watchAdButton.addEventListener('click', async () => {
+  watchAdButton.disabled = true; // only between the press and the answer
+  try {
+    await gem.ads.requestAd({ placement: 'classic_revive', format: 'rewarded' });
+    gem.me.inventory.refresh();
+    const snap = await gem.me.inventory.snapshot();
+    // ...decide from `snap`, never from the outcome
+  } finally {
+    watchAdButton.disabled = false; // or redraw it from `rewardedStatus` (§5)
+  }
+});
+```
+
+**Ask first, inside the button's own handler.** The press is the player's opt-in, and the Arcade
+starts the ad as soon as the ask arrives. A browser counts a press for only a few seconds, so put
+the ask before any `await` or timer that could outlast it. A tap, click or key press counts, and
+so does a controller press in the last second. Where the browser reports user activation, your
+frame holds none, and no controller was used in the last second, the SDK (releases after 9.0.0)
+answers `no_ad` without asking. Your `onError` handler then gets code `'internal'` and a message that begins
+`rewarded_requires_user_gesture`, and the SDK writes the same line to the console once, as a
+`[gem]` line, unless you set `log: null`. Where the browser cannot tell, the ask goes ahead.
+
+**Which handler counts is the browser's decision, and two common ones do not:**
+
+- **Ask from `click`, `pointerup`, `touchend` or `keydown`.** On a phone, `click` and `pointerup`
+  arrive after the finger lifts, which is when the browser counts the tap.
+- **Never from `pointerdown` or `touchstart`.** On a touchscreen they run _before_ the browser
+  counts the tap, so the ask is refused, except when an earlier tap happened a few seconds before.
+  With a mouse, `pointerdown` does count, so **testing at a desk will not show this**. Test the
+  button on a phone. A three.js button picked by a raycast on `pointerdown` is the usual way to hit
+  it: raycast on `pointerup` or `click` for this button.
+- **A controller press counts for one second.** Browsers do not treat gamepad input as a press,
+  so the SDK counts it itself: the ask goes ahead when any connected controller's state changed in
+  the last second. Ask from the frame of your input loop that saw the button go down, not after a
+  menu animation or a timer. A TV remote needs none of this: its buttons arrive as key presses,
+  and they count like any other.
+
+A refusal is your bug to fix. It is usually a read placed in front of the ask, a handler on
+`pointerdown`, or an ask on a timer.
+
+**It is a check for a mistake, not a control.** It catches an ask with no recent input at all. It
+cannot tell which input caused the ask: a browser counts any tap in your game for a few seconds,
+and the SDK counts any controller input for one, so an ask from your jump button's handler, or
+from a death a second after a tap, goes through.
+Making the ask only from the button is yours to get right.
+[`cross-promotion.md`](cross-promotion.md#where-to-put-the-call) has the handler.
+
+The answer is one of the same three outcomes every `requestAd` gets — `shown`, `no_ad` or
+`unavailable` — and for `rewarded` none of them says whether a reward was granted. What can happen
+after a press:
+
+| what happened                                                                             | was the reward granted?                                                                                                                             |
+| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| the ad played for its full length                                                         | yes, before the answer                                                                                                                              |
+| the player closed the ad early                                                            | no: closing early is a skip, and a skip pays nothing                                                                                                |
+| an ad source serves, but no ad was available for this press, or it failed to play         | your `without_ads` decides: `grant` grants within your caps, with no ad; `nothing` grants nothing, and the Arcade shows "No ad available right now" |
+| no ad source serves the channel (§8)                                                      | your `without_ads` decides, with no ad                                                                                                              |
+| a cap, a cooldown, `max_held`, the platform's spacing (§6), or something about the player | no                                                                                                                                                  |
+
+In some cases the platform also grants with no ad for reasons your game is not told. So **branch on
+your inventory, never on the outcome.** Re-read it once the ask settles, whatever it settled as.
+
+**A reward can also arrive after that re-read.** Some ad providers confirm a finished ad from their
+own server, a little after the player closes it, so the reward can land after the ask has
+answered. So also re-read when the screen that spends the reward opens, and spend a token the
+player already holds before asking for another (§5's code does both).
+[`inventory-and-catalogs.md` §6](inventory-and-catalogs.md#6-when-to-re-read) is the general rule.
+
+A granted reward shows in your order history like any other change, as an order the platform made
+with `source` `reward`.
+
+**While the ad plays, your game is paused,** the same way it is for an interstitial: the Arcade
+sends the pause your game already handles and lifts it when the ad closes. Resume when the promise
+settles, not on a timer. A second `requestAd` while one is still in flight resolves `no_ad` at once,
+so disable the button between the press and the answer.
+
+## 4. Spend it with a recipe
+
+Using the reward — the revive itself — is a server call: a recipe that removes the token. There is
+no `consume` recipe type; a consume is an `exchange` whose `costs` remove the item. In one of your
+catalogs:
+
+```yaml
+- id: '<uuid>'
+  slug: use_revive
+  recipe_type: exchange
+  client_writable: true # the RECIPE is client-executable; the ITEM stays client_writable: false
+  costs:
+    - { type: item_remove, item_definition_slug: revive_token, quantity: 1 }
+```
+
+```js
+await gem.me.mutations.executeRecipe(ACTIONS_CATALOG_ID, USE_REVIVE_RECIPE_ID);
+revive(); // only after the recipe resolves
+```
+
+The server checks that the player holds a token and removes it in the same step, which a modified
+client cannot fake. **Apply the revive only after the recipe resolves.**
+
+**If it fails, do not send it again; re-read the inventory.** A timeout or a dropped connection
+proves nothing — the spend may have landed — so let the inventory decide, as it does for the
+reward itself: a token that was there before the call and is gone now was spent, and one that is
+still there was not. [`inventory-and-catalogs.md`
+§11](inventory-and-catalogs.md#11-conditional-writes-and-why-most-writes-do-not-want-them) is the
+general rule for a write that timed out.
+
+Why not remove the item from the client with a mutation? Because that needs the item to be
+`client_writable`, and then a modified client can grant it too (§1).
+
+**If the reward feeds anything competitive, check the spend on your server.** An extra attempt at a
+daily puzzle that posts to a leaderboard is only as honest as whatever accepts the result: the
+server or function that does should confirm each attempt beyond the free one spent a token. A
+client-side check is a check a modified client skips.
+
+## 5. Draw the button only when it can pay
+
+**The button says it is an ad, and names the reward:** "Watch an ad to revive", "Watch an ad for 3
+dice rolls". The press is the player's choice to watch, and the Arcade starts the ad without asking
+again, so your label is what tells the player an ad follows.
+
+- **Never a label that hides the ad,** and never one that reads as the only way forward. "Tap to
+  continue" on a button that starts an ad disguises the ask. Draw the ordinary way on — end the
+  run, back to the menu — beside it, so pressing it is a choice.
+- **The same label in every state.** Where no ad plays (§8), the press pays without one. The label
+  promised an ad the player did not have to watch, which is fine.
+- **When the press paid nothing**, carry on, and show a neutral line in your own UI such as "No
+  revive this time". Never guess a reason: you are not told one. When no ad was available and
+  nothing was granted, the Arcade has already said "No ad available right now", so your line need
+  not repeat it.
+
+**A game built under the earlier guide must be rebuilt and relabelled.** The guide before this one put an offer sheet of the Arcade's own in front of every rewarded ad, so its button could say "Revive" with no mention of an ad. There is no sheet any more, so that button now starts an ad unannounced. Rebuild on an SDK with the press check (§3) and relabel the button by this section before paid ads come to the Arcade. Until then, rewarded on such a game only ever shows test ads to its own team and testers.
+
+Your own rules decide when the button appears at all — once per run, only on the death screen,
+never in a ranked mode — because the platform cannot see a run (§6).
+
+**Within those rules, draw it only when `gem.ads.rewardedStatus` says it can pay** (SDK 8.1.0 and
+later). The status reads the placement's caps as the platform holds them: `declared`, `grantable`,
+`remainingToday`, `nextEligibleAt`, `heldLimitReached` and `resetsAt`. `grantable` is `false` when
+a cap is spent, a cooldown runs, the player holds `max_held`, or rewarded is off on the channel, so
+drawing on it never offers a press that is certain to pay nothing. Hide or grey the button out
+otherwise, and say when it is back from `nextEligibleAt` or `resetsAt`. `grantable` is not a
+promise: a press can still pay nothing for reasons the read never reports. The status reserves
+nothing, and it never rejects. See [cross-promotion.md](cross-promotion.md):
+
+```js
+const status = await gem.ads.rewardedStatus('classic_revive');
+watchAdButton.hidden = !status.grantable;
+```
+
+For a revive, the screen reads what it needs **when it opens**, so the press itself can ask at
+once:
+
+```js
+async function reviveTokens() {
+  gem.me.inventory.refresh(); // drop what is cached
+  try {
+    // Every revive_token the player holds, read by the slug from your config.
+    const held = await gem.me.inventory.instances('revive_token');
+    return held.reduce((n, item) => n + item.quantity, 0);
+  } catch (err) {
+    // A player who holds none of an item is answered `not_found`, not an empty
+    // list. That is a count of zero, and it is the usual case: the first press,
+    // and the re-read after a spend that took the last token.
+    if (err?.reason === 'not_found') return 0;
+    throw err;
+  }
+}
+
+async function spendRevive(before) {
+  try {
+    await gem.me.mutations.executeRecipe(ACTIONS_CATALOG_ID, USE_REVIVE_RECIPE_ID);
+    return true;
+  } catch {
+    // Refused, or no answer. A spend that timed out may still have landed, so never
+    // send it again: the inventory decides (§4).
+    return (await reviveTokens()) < before;
+  }
+}
+
+// When the death screen opens: the reads happen here, before any press.
+async function drawReviveButtons() {
+  useTokenButton.hidden = true;
+  watchAdButton.hidden = true;
+  if (run.revived) return; // the game's own rule: one revive per run
+  try {
+    if ((await reviveTokens()) > 0) {
+      // A token left over from earlier is spent first, with no ad.
+      useTokenButton.textContent = 'Use a revive token';
+      useTokenButton.hidden = false;
+      return;
+    }
+  } catch {
+    return; // a read failed: no revive on offer this time
+  }
+  const status = await gem.ads.rewardedStatus('classic_revive');
+  watchAdButton.textContent = 'Watch an ad to revive';
+  watchAdButton.hidden = !status.grantable;
+}
+
+async function onWatchAdPressed() {
+  watchAdButton.disabled = true; // only between the press and the answer
+  // FIRST, inside the click. Anything awaited before this can outlast the press.
+  await gem.ads.requestAd({ placement: 'classic_revive', format: 'rewarded' });
+  await reviveIfHeld(); // whatever the answer was
+  watchAdButton.disabled = false;
+}
+
+async function onUseTokenPressed() {
+  useTokenButton.disabled = true;
+  await reviveIfHeld();
+  useTokenButton.disabled = false;
+}
+
+// `click`, never `pointerdown`: on a phone, a `pointerdown` runs before the tap counts (§3).
+watchAdButton.addEventListener('click', onWatchAdPressed);
+useTokenButton.addEventListener('click', onUseTokenPressed);
+
+async function reviveIfHeld() {
+  let revived = false;
+  try {
+    const held = await reviveTokens(); // the re-read after the ask
+    revived = held > 0 && (await spendRevive(held));
+  } catch {
+    // A read failed. That is no revive this time.
+  }
+  if (revived) {
+    run.revived = true;
+    revive(); // only once the spend is known to have landed
+  } else {
+    showNoRevive(); // "No revive this time": neutral, and no reason
+  }
+  await drawReviveButtons(); // redraw from the new state
+}
+```
+
+## 6. Caps live on the placement
+
+The caps are **yours to declare and the platform's to enforce.** The reward is your game's own
+economy, so you choose its limits, and the platform holds them on its side, where a modified client
+cannot reach them. They apply the same with an ad and without one.
+
+| limit                                                                                    | declared by           | enforced by   |
+| ---------------------------------------------------------------------------------------- | --------------------- | ------------- |
+| `max_per_day` — grants per player per UTC day                                            | you, optionally       | the platform  |
+| `cooldown_seconds` — the time between two grants                                         | you                   | the platform  |
+| `max_held` — no grant while the player holds this many                                   | you, for item rewards | the platform  |
+| `min_watch_secs` — how long a test ad plays before it pays                               | you, optionally       | the platform  |
+| at least 15 seconds between two rewarded offers to one player in one game                | the platform          | the platform  |
+| at least 15 seconds between two rewards granted with no ad, in any of the player's games | the platform          | the platform  |
+| once per run, only on the death screen, never in ranked                                  | you                   | **your game** |
+
+- **The second spacing reaches across games.** If another game granted this player a reward with
+  no ad a few seconds ago, an ask in yours that would also grant with no ad (§8) answers `no_ad`
+  with nothing granted, even though your game has offered nothing.
+- **What counts toward a cap** is a grant, after an ad or with none, and an ad that is still
+  playing. A grant `without_ads: grant` makes because no ad could play counts the same as any
+  other. An ad the player closed early, and a press that paid nothing, do not count, so a skip
+  costs the player nothing against your caps. Every press does start the first spacing, though:
+  a player who closes the ad early and presses again within 15 seconds gets `no_ad` and nothing.
+- **The platform may hold a daily cap lower than the one you declared, never higher.** It sets no
+  daily limit of its own unless one is configured, and a configured one applies to every placement
+  from the next ask, with no upload from you.
+- ⚠️ **Nothing protects your economy by default but your own caps.** A placement with no
+  `max_per_day` and no `cooldown_seconds` can pay once every 15 seconds. That holds with an ad,
+  and under `without_ads: grant` without one, wherever no ad plays. `max_held: 1` stops a player
+  banking a second token; it does not stop them spending one and earning the next. Declare the
+  daily cap and cooldown your economy needs.
+- **`without_ads: grant` means the reward is fine to give free, within its caps.** Every press
+  that finds no ad pays under it, so the caps are all that limit it. Choose `nothing` for a reward
+  that should only ever follow an ad.
+- **"Once per run" is yours.** The platform has no idea what a run is. `max_held: 1` is the
+  backstop that keeps it hard to abuse: a player can never hold two revives at once.
+
+This is the opposite of the rule for platform currencies, where a game declares no caps and the
+platform sets them all. A rewarded reward is your economy, so the caps are yours.
+
+## 7. Pacing
+
+- **A rewarded ask is never held back by an interstitial.** A player who presses your button is not
+  refused because a promotion played a minute ago, in your game or another.
+- **An ad that starts holds off the next interstitial.** Do not follow a rewarded ad with an
+  interstitial at the same break; that ask answers `no_ad`.
+- **Rewarded has its own spacing:** your placement's `cooldown_seconds`, and the platform's 15
+  seconds (§6). An ask inside any of them answers `no_ad` with nothing granted, so do not re-ask on
+  a timer. Never ask on a timer at all: the ad would start with no press. The SDK refuses a timer's
+  ask only when no input came in the last few seconds (§3), so do not count on it. A player who
+  presses again later gets a fresh ask.
+- A grant made with no ad holds nothing off, because nothing was shown.
+
+## 8. Where an ad plays, and where it does not
+
+Each channel of your game is in one of these states at a time. Which one is the platform's to set,
+not yours, and moving between them needs **no rebuild and no config change**:
+
+| state                | channels              | what pressing the button does                                                                                                                                                                                                                    |
+| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Off**              | any                   | Every rewarded ask answers `no_ad`, and nothing is granted.                                                                                                                                                                                      |
+| **A — test ads**     | `dev` and `test` only | The Arcade plays a test ad at once, marked **TEST AD**, for the placement's `min_watch_secs`. Watching it to the end grants the reward for real, into that channel's inventory only (§10). Where the test ad has no fill, `without_ads` decides. |
+| **B — no ad source** | `release`             | No ad plays. Under `without_ads: grant` the reward is granted within your caps, with no ad, and the ask answers `no_ad`. Under `nothing`, nothing is granted.                                                                                    |
+| **C — an ad source** | `release`             | The Arcade plays an ad at once, labelled as an ad, and the reward is granted once the ad finishes. Where no ad is available for the press, or it fails to play, `without_ads` decides.                                                           |
+
+**On gemarcade.com, every channel is Off today**, `dev` and `test` included. Every rewarded ask
+there answers `no_ad` and grants nothing, whatever your placement's `without_ads` says, and
+`rewardedStatus` answers not `grantable`, so a button drawn on it (§5) does not show yet. Test ads
+(state A) are switched on there first; until then you can ship the code in §3–§5, and the day a
+channel's state changes it starts working with no rebuild. The platform's internal test
+environment already runs state A on `dev` and `test` and state B on `release`, which is where the
+platform rehearses it before gemarcade.com. **Test ads never serve on `release`**, and a reward
+granted on `dev` or `test` never reaches `release`: inventory is per channel.
+
+What each state means for a game:
+
+- **Build the final shape now.** The code in §5 is the same code in every state. Under
+  `without_ads: grant`, a reward that should be free until ads serve is free in state B: the same
+  benefit, under the same caps. In state C the same placement plays an ad when one is available.
+  It still pays with no ad whenever no ad can play for a press, because no ad was available or the
+  ad failed. So in state C too, a `grant` placement's caps are the only limit on it. There is
+  nothing to change between states. Choose `nothing` if a reward should only ever follow an ad.
+- **The watch time is the platform's to measure, and the provider's to decide.** For a test ad,
+  the platform refuses a completion that comes sooner than the placement's `min_watch_secs`. A
+  real ad provider decides for itself when its ad has finished, so for a real ad the value is the
+  length the Arcade asks for, and the ad may run longer or shorter.
+- **In state C, some players get nothing for a press.** The platform does not show network ads to
+  some players at all: that is a rule about the player, such as where they are or a privacy setting
+  their browser sends. Such a player gets `no_ad` and no reward, and `without_ads` does not apply to
+  them. This is not the same as a press that found no ad available, which `without_ads` decides
+  (the table above). Your game is not told which players those are. So a placement that is free for
+  everyone in state B is not free for every player in state C. Write §5's "No revive this time"
+  path as an ordinary path, because it is one.
+- **A visitor with no Arcade account, not even a guest one, is never rewarded**, in any state.
+
+## 9. The placement stays on the platform
+
+Your placement name goes to the platform, which matches it against your config, and **never to an
+ad network** — and neither does any other string your game writes. So:
+
+- **Name a placement for the reward, for your own reading** — `classic_revive`, `daily_drop_extra`.
+  There is nothing to provision and nothing to register with a network, so a placement you declare
+  later serves like any other.
+- **Do not put an identifier in it**, and do not expect to see it on any ad report. Per-placement
+  numbers are the platform's, not a network's.
+- **Never embed an ad SDK or ad tag in your game.** The Arcade plays every ad itself; your game
+  asks, and reads its inventory.
+
+## 10. Testing it
+
+Where your `dev` and `test` channels are in state A (§8), rewarded is testable end to end against
+the **test ad** source, before any real ad serves. Test grants are real: they land in that
+channel's inventory, so your game's re-read finds them and §4's recipe spends them.
+
+Before you start:
+
+1. `gemctl config schema` lists `rewarded_placements` (§2), and `min_watch_secs` if you set it.
+2. The config version promoted to the channel declares your placement, and your items and recipe.
+3. The channel has a build and a store page, so it appears in the Arcade at all.
+
+**Press the button the way a player does.** An ask with no user activation is refused before it
+leaves your game (§3), so an automated test should press the button through its driver's real
+input, such as Playwright's `click` or `tap`. Do not test the check itself from the console or
+from `page.evaluate`, because both usually count as a press:
+
+- Playwright runs every `evaluate` as a user gesture. An ask made straight from one goes through in
+  Chromium, Firefox and WebKit.
+- Chrome's DevTools console treats what you type as a user action by default.
+
+So an ask from either proves nothing about your button. To see the refusal on purpose, make the
+ask from a timer in your page that fires well after the last input, ten seconds say, with no
+driver call into your game in between.
+
+**Test the button on a phone,** or with touch emulation in Chromium or Firefox (Playwright's `tap`
+in a context with `hasTouch`). A `pointerdown` handler passes with a mouse and is refused on a
+touchscreen (§3), so a desk test with a mouse cannot show it.
+
+### At the Arcade, on `dev` or `test`
+
+Play your game on its `dev` or `test` channel. `dev` is open to your team and `test` to your
+testers. Pressing the button starts a test ad at once, marked **TEST AD**, which counts down the
+placement's `min_watch_secs` (5 seconds unless you set it). Watch it to the end and the reward
+lands in that channel's inventory. Close it before then and that is a skip, which pays nothing.
+Your game is paused while it plays, and the ask answers when it closes.
+
+To pick a behaviour before you press, add `gem_test_ads=<mode>` to the play page's address:
+
+| `gem_test_ads=` | what it does                                                                                                                                                                |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `instant`       | completes the test ad when its countdown ends, with no click                                                                                                                |
+| `no_fill`       | the test source has no ad, so your placement's `without_ads` decides: `grant` grants with no ad; `nothing` grants nothing, and the Arcade shows "No ad available right now" |
+| `fail`          | the test ad fails to play, which `without_ads` decides exactly as it does for `no_fill`                                                                                     |
+| `skip`          | the test ad starts and is skipped: no reward                                                                                                                                |
+| `free`          | asks as if no ad source served the channel, so your placement's `without_ads` decides with no ad at all. This is how you see state B before you ship                        |
+
+`gem_test_ads` is for the Arcade's play page, not your game, and it does nothing on `release`.
+
+On `dev` and `test`, when a press pays nothing, or pays with no ad, for a reason that is about your
+config or your caps, the Arcade writes **one console line** saying which. It is never shown to a
+player, and never written on `release`:
+
+```text
+[gem] rewarded 'clasic_revive' on dev: placement not declared in this channel's config; nothing granted
+[gem] rewarded 'classic_revive' on dev: the player already holds the placement's max_held; nothing granted
+[gem] rewarded 'classic_revive' on dev: granted without an ad (no ad source on this channel)
+```
+
+The lines it can write are config and cap facts only: the placement is not declared, no config is
+promoted to the channel, the daily cap is reached, the cooldown is running, `max_held` is reached,
+the ask came inside the 15-second spacing, the allowance is spent, the reward was granted with no
+ad, or rewarded is off on the channel. Your game sees none of them, and a no that is about the
+player is never written there.
+
+An ask made without the player's press (§3) never reaches the Arcade, so the Arcade writes nothing
+for it. The SDK writes its own line instead, once a session, beginning
+`[gem] rewarded_requires_user_gesture`, and your `onError` handler gets the same message.
+
+**No ad and no console line at all** means the no was about something those lines never cover:
+
+- an ask made without the player's press, under `log: null`, which silences the SDK's line; your
+  `onError` handler still has it;
+- rewarded is not switched on in the Arcade you are playing in at all (where it is on but off for
+  your channel, the line says so);
+- your game asked while its page was hidden, or while another Arcade panel was over it;
+- the reward would not fit under a limit on the item or currency itself — a currency's maximum
+  balance, say. Only `max_held` is reported, so declare it rather than lean on the item's own
+  limit;
+- under `gem_test_ads=free`, a placement that says `without_ads: nothing`;
+- something about the player or their session, which is never written.
+
+### In the dev host
+
+`gemctl serve` and the Gem Editor play a rewarded ask through the same test-ad source, for your
+game's **`dev`** channel, as **your own account**. A claimed reward is real: it lands in your own
+`dev` inventory for that game, so your re-read and §4's recipe behave as they will at the Arcade.
+
+- **Pick the behaviour on the framing page's Start screen.** The default plays the test ad for
+  the placement's watch time. `instant` pays with no clicks, which is the one an automated test
+  wants. `abandon` starts the ad and closes it before the end: a skip, so nothing is paid. `no_fill` has no ad, so `without_ads` decides. `error` answers `unavailable` with nothing
+  asked. `free` rehearses `without_ads` with no ad (§8). You can also add `?rewarded=<mode>` to
+  the framing page's own address, but not to the link `gemctl serve` prints, because its redirect
+  drops the query.
+- **Each ask writes one line** saying what happened, and why when nothing arrived, to
+  `gemctl serve log`, the Editor's Log page and the page's console.
+- **Signed out, a game not linked to your project, the Editor's game window, or another device on
+  the network** get a panel marked **Simulated**, and nothing is granted.
+- **It works where your game's `dev` channel serves test ads (state A).** The dev host talks to
+  gemarcade.com, so until test ads are switched on there, every offer answers that rewarded ads
+  are not served yet.
+- **To test a cap again today**, clear your own rewarded use for the day:
+  `gemctl rewarded reset --game <game id> --channel dev` (or `test`, and `--placement P` for one
+  placement). It is refused on `release`, it touches only your own account, and it leaves your
+  inventory alone, so a `max_held` that is reached stays reached until you spend the reward.
+
+## If you do nothing
+
+Nothing happens. A game that never asks for `rewarded` never starts an ad, and nothing here is on
+the list of things a game must do to ship. A rewarded ask for a placement your config does not
+declare answers `no_ad` and grants nothing.