@indiegems/gem-web-sdk 8.0.0 → 9.0.0

package/docs/rewarded-ads.md

@@ -0,0 +1,464 @@
+# Rewarded ads
+
+A rewarded placement is a button your player presses for something your game gives — a revive, an
+extra attempt at today's puzzle. Your game asks the Arcade. Where an ad serves, the Arcade shows its
+own offer sheet and then the ad; either way the platform 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
+await gem.ads.requestAd({ placement: 'classic_revive', 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, saying what one press grants and how often (§2).
+3. **A spend** — the recipe your game runs when the player uses the reward (§4).
+4. **A button** that names the reward (§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`.** The Arcade prints it on its offer sheet — "1 × Revive token" — 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 offer sheet cuts a longer one short.
+
+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 offer sheet says "1 × Revive token"
+    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 happens where no ad serves
+  - placement: daily_drop_extra
+    grants:
+      - { type: item_grant, item_definition_slug: daily_drop_attempt, quantity: 1 }
+    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 an `amount`; an `item_grant` takes a `quantity`.                                                                                                               |
+| `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 an ask gets where no ad serves your channel (§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 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, 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.
+
+## 3. Ask, then re-read
+
+```js
+await gem.ads.requestAd({ placement: 'classic_revive', format: 'rewarded' });
+gem.me.inventory.refresh();
+const snap = await gem.me.inventory.snapshot();
+```
+
+The answer is one of the same three outcomes every `requestAd` gets, and for `rewarded` none of
+them says whether a reward was granted:
+
+| outcome       | what happened                                                                          | was anything granted?                                                                                                                                                                                |
+| ------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `shown`       | the Arcade painted its offer sheet, and it has closed, whatever the player chose in it | if the player watched to the end, yes, before the answer; if they declined or skipped, or no ad was available after all, no                                                                          |
+| `no_ad`       | nothing was painted                                                                    | maybe: in some cases the platform grants with no ad — where no ad serves and the placement says `without_ads: grant` (§8), for one — and then the reward was granted before the answer. Otherwise no |
+| `unavailable` | the Arcade could not ask                                                               | almost always no, but read your inventory anyway                                                                                                                                                     |
+
+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. The Arcade waits a few seconds for that, then
+tells the player "Your reward is on its way", and the ask answers `shown` when its sheet closes,
+with the reward still to come. 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 Arcade's sheet is up, 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 sheet 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, and name the reward
+
+**Label the button with what the player gets — "Revive", "+1 attempt" — and nothing else.**
+
+- **Do not write "Watch an ad to …".** Where no ad serves (§8), no ad plays, and the label would be
+  false. The Arcade's offer sheet is the ad disclosure: it says that it is an ad and what the player
+  gets, and offers "No thanks", before anything plays, and it appears only when an ad will.
+- **Never a label that reads as the only way forward.** "Tap to continue" on a button that asks
+  for 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.
+- **When the press paid nothing**, show a neutral line in your own UI — "No revive this time" —
+  and carry on. Never guess a reason: you are not told one.
+
+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).
+
+**Whether it can pay right now is `gem.ads.rewardedStatus`** (SDK 8.1.0 and later). It reads the
+placement's caps as the platform holds them, `declared`, `grantable`, `remainingToday`,
+`nextEligibleAt`, `heldLimitReached` and `resetsAt`, so you can grey the button out or say when it
+is back instead of offering a press that cannot pay. `grantable` is not a promise: an ask can still
+answer `no_ad` for reasons the read never reports. It reserves nothing, and it never rejects. See
+[cross-promotion.md](cross-promotion.md):
+
+```js
+const status = await gem.ads.rewardedStatus('classic_revive');
+reviveButton.disabled = !status.grantable;
+```
+
+For a revive, the button's handler:
+
+```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;
+  }
+}
+
+async function onRevivePressed() {
+  if (run.revived) return; // the game's own rule: one revive per run
+  reviveButton.disabled = true; // only between the press and the answer
+  let revived = false;
+  try {
+    if ((await reviveTokens()) === 0) {
+      // A token left over from earlier is spent first, so ask only when there is none.
+      await gem.ads.requestAd({ placement: 'classic_revive', format: 'rewarded' });
+    }
+    const held = await reviveTokens();
+    revived = held > 0 && (await spendRevive(held));
+  } catch {
+    // A read failed. That is no revive this time; the player can press again.
+  }
+  reviveButton.disabled = false;
+  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
+  }
+}
+```
+
+## 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  |
+| 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, with or without an ad, and an ad that is still playing.
+  An offer the player declined, one no ad was available for, and an ad that was skipped or failed
+  do not count, so "No thanks" costs the player nothing against your caps. Every offer does start
+  the first spacing, though: a player who says "No thanks" 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 — with an ad, or, under
+  `without_ads: grant`, without one. `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.
+- **"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. 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 paints a sheet marked **Test ad**. Finishing the test ad grants the reward for real, into that channel's inventory only (§10).                     |
+| **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's offer sheet, then an ad; the reward is granted once the ad finishes. `without_ads` does not apply.                                               |
+
+**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, so a button
+you ship pays nothing yet. Test ads (state A) are switched on there first; until then you can ship
+the code in §3–§5, which answers `no_ad`, 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 game whose reward should be free until ads serve — the same benefit, under the same caps
+  — gets exactly that in state B, and the same placement shows an ad first in state C, with nothing
+  to change. Choose `nothing` if a reward should only ever follow an ad.
+- **In state C, some players get nothing for a press.** A player the ad source cannot serve gets
+  `no_ad` and no reward, and `without_ads` does not apply to them. 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).
+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.
+
+### 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 paints the Arcade's sheet, marked **Test ad**, naming your reward and
+saying the reward lands on that channel only. **Watch** opens a test stage with a short countdown,
+then **Claim reward**; the reward lands, the sheet says what was received, and the ask answers
+`shown` when the player presses **Continue**. **No thanks** answers `shown` with nothing granted,
+and so does a sheet nobody answers, which declines itself after a minute.
+
+The test sheet also has **Simulate no fill**, **Simulate failure** and **Skip (no reward)**, each
+answering `shown` with nothing granted. To pick a behaviour before the sheet opens, add
+`gem_test_ads=<mode>` to the play page's address:
+
+| `gem_test_ads=` | what it does                                                                                                                                                                                                  |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `instant`       | after **Watch**, claims the reward when the countdown ends, with no **Claim reward** click; **Continue** still closes the sheet                                                                               |
+| `no_fill`       | the sheet reports that no ad was available; **Close** answers `shown`, no reward                                                                                                                              |
+| `fail`          | **Watch** fails at once; **Continue** answers `shown`, no reward                                                                                                                                              |
+| `skip`          | **Watch** starts the ad and skips it: `shown`, no reward                                                                                                                                                      |
+| `free`          | asks as if no ad source served the channel, so your placement's `without_ads` decides: `grant` grants with no sheet and answers `no_ad`; `nothing` gives nothing. This is how you see state B before you ship |
+
+**Only `free` needs no click.** The default, `instant`, `fail` and `skip` open on the offer sheet
+and wait for a person to press **Watch**, so an automated test that cannot press it waits out the
+minute, after which the sheet declines itself and the ask answers `shown` with no reward.
+`no_fill` has no such timer: its sheet waits for **Close**, so an unattended test gets
+`unavailable` when the SDK stops waiting, after three minutes, with the sheet still up.
+
+`gem_test_ads` is for the Arcade's play page, not your game, and it does nothing on `release`.
+
+On `dev` and `test`, when an ask paints no sheet 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.
+
+**No sheet and no console line at all** means the no was about something those lines never cover:
+
+- 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 sheet, then **Watch**, a
+  2-second test stage, then **Claim reward**; `instant`, which pays with no clicks (the one an
+  automated test wants); `decline`; `abandon`; `no_fill`; `error`, which answers `unavailable`
+  with nothing asked; and `free`, which rehearses `without_ads` with no sheet (§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` is never shown a sheet, 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.