@indiegems/gem-web-sdk 13.1.0 → 13.2.0

package/schema/capabilities.public.json

@@ -242,6 +242,16 @@
       "gates": [
         "gem.gemCorner"
       ]
+    },
+    "moments": {
+      "implemented": true,
+      "gates": [
+        "gem.signalMoment",
+        "gem.momentResult",
+        {
+          "namespace": "gem.moments"
+        }
+      ]
     }
   }
 }

package/schema/moment-log-line.json

@@ -0,0 +1,109 @@
+{
+  "$comment": [
+    "The one structured log line a development host writes for each platform",
+    "moment: `gem.signalMoment` from the game, and the deprecated",
+    "`gem.requestAd` with `format: 'interstitial'` as `kind=legacy`. Every dev",
+    "host writes it exactly as below, and asserts the `cases` here, so that a",
+    "release checklist reading the log of one host reads every host's.",
+    "",
+    "WRITTEN ONCE PER MOMENT, WHEN THE HOST ANSWERS IT. Fields in this order,",
+    "separated by one space, `name=value`, nothing before `moment` and nothing",
+    "after `answer`. A value that is absent is written `-`.",
+    "",
+    "  kind            the moment's kind, or `legacy` for an interstitial ask.",
+    "  placement       the game's own name for the screen, when it gave one",
+    "                  that fits `^[a-z0-9_-]{1,32}$`; `-` when it gave none,",
+    "                  and `?` when it gave one outside that grammar. The value",
+    "                  is untrusted text: a host never prints one that fails",
+    "                  the grammar, and never forwards one anywhere.",
+    "  since_ready_ms  whole milliseconds from the frame's `gem.ready` to this",
+    "                  moment's arrival; `-` when `gem.ready` has not arrived.",
+    "  since_prev_ms   whole milliseconds from the previous moment's arrival in",
+    "                  this session to this one's; `-` for the first.",
+    "  answer          `shown` when the host painted something, `not_shown`",
+    "                  otherwise.",
+    "",
+    "A CONTRACT, NOT A WIRE MESSAGE. It never crosses the bridge and no game",
+    "reads it. Adding a field is a new version of this file; a host that",
+    "writes this version writes exactly these five."
+  ],
+  "version": 1,
+  "prefix": "moment",
+  "fields": [
+    {
+      "name": "kind",
+      "values": ["level_end", "run_end", "match_end", "menu_return", "other_break", "legacy"]
+    },
+    { "name": "placement", "pattern": "^[a-z0-9_-]{1,32}$", "absent": "-", "outsideGrammar": "?" },
+    { "name": "since_ready_ms", "pattern": "^(0|[1-9][0-9]*)$", "absent": "-" },
+    { "name": "since_prev_ms", "pattern": "^(0|[1-9][0-9]*)$", "absent": "-" },
+    { "name": "answer", "values": ["shown", "not_shown"] }
+  ],
+  "pattern": "^moment kind=(level_end|run_end|match_end|menu_return|other_break|legacy) placement=([a-z0-9_-]{1,32}|-|\\?) since_ready_ms=(0|[1-9][0-9]*|-) since_prev_ms=(0|[1-9][0-9]*|-) answer=(shown|not_shown)$",
+  "cases": [
+    {
+      "$comment": "The ordinary moment: a level ended, a placement given, nothing shown.",
+      "moment": {
+        "kind": "level_end",
+        "placement": "world-1-3",
+        "sinceReadyMs": 84210,
+        "sincePrevMs": 61005,
+        "shown": false
+      },
+      "line": "moment kind=level_end placement=world-1-3 since_ready_ms=84210 since_prev_ms=61005 answer=not_shown"
+    },
+    {
+      "$comment": "The first moment of a session, with no placement, and a panel shown.",
+      "moment": { "kind": "run_end", "sinceReadyMs": 152000, "shown": true },
+      "line": "moment kind=run_end placement=- since_ready_ms=152000 since_prev_ms=- answer=shown"
+    },
+    {
+      "$comment": "A return to the menu.",
+      "moment": {
+        "kind": "menu_return",
+        "placement": "pause_quit",
+        "sinceReadyMs": 301442,
+        "sincePrevMs": 90010,
+        "shown": false
+      },
+      "line": "moment kind=menu_return placement=pause_quit since_ready_ms=301442 since_prev_ms=90010 answer=not_shown"
+    },
+    {
+      "$comment": "A placement outside the grammar, from a frame that posted on the port directly: never printed.",
+      "moment": {
+        "kind": "match_end",
+        "placement": "Round 3\nanswer=shown",
+        "sinceReadyMs": 600000,
+        "sincePrevMs": 240000,
+        "shown": false
+      },
+      "line": "moment kind=match_end placement=? since_ready_ms=600000 since_prev_ms=240000 answer=not_shown"
+    },
+    {
+      "$comment": "A moment before `gem.ready`, which the SDK never sends but a frame on the port can.",
+      "moment": { "kind": "other_break", "shown": false },
+      "line": "moment kind=other_break placement=- since_ready_ms=- since_prev_ms=- answer=not_shown"
+    },
+    {
+      "$comment": "The deprecated interstitial ask, logged on the same line so a checklist sees it.",
+      "moment": {
+        "kind": "legacy",
+        "placement": "level-complete",
+        "sinceReadyMs": 45000,
+        "sincePrevMs": 0,
+        "shown": false
+      },
+      "line": "moment kind=legacy placement=level-complete since_ready_ms=45000 since_prev_ms=0 answer=not_shown"
+    }
+  ],
+  "notLines": [
+    "moment kind=boss_end placement=- since_ready_ms=1 since_prev_ms=- answer=not_shown",
+    "moment kind=level_end placement=World-1 since_ready_ms=1 since_prev_ms=- answer=not_shown",
+    "moment kind=level_end placement=- since_ready_ms=-5 since_prev_ms=- answer=not_shown",
+    "moment kind=level_end placement=- since_ready_ms=1.5 since_prev_ms=- answer=not_shown",
+    "moment kind=level_end placement=- since_ready_ms=1 since_prev_ms=- answer=true",
+    "moment kind=level_end since_ready_ms=1 placement=- since_prev_ms=- answer=not_shown",
+    "moment kind=level_end placement=- since_ready_ms=1 since_prev_ms=- answer=not_shown ",
+    "[gem] moment kind=level_end placement=- since_ready_ms=1 since_prev_ms=- answer=not_shown"
+  ]
+}

package/docs/cross-promotion.md

@@ -1,232 +0,0 @@
-# Cross-promotion
-
-The Arcade can show a **full-screen panel about another game** at a break in yours. Your game asks
-for one; the Arcade decides whether to show anything, draws it in its own chrome over your paused
-game, and tells you when it is done.
-
-The same call with `format: 'rewarded'` is a button the player presses for something your game
-gives — a revive, an extra attempt. That one has its own page,
-[`rewarded-ads.md`](rewarded-ads.md). This page is about the interstitial; where a rule here reads
-differently for a rewarded ask, it says so.
-
-```js
-const { outcome } = await gem.ads.requestAd({
-  placement: 'level-complete',
-  format: 'interstitial',
-});
-// Nothing to handle. Carry on.
-startNextLevel();
-```
-
-That is the whole surface, apart from one read that tells a rewarded button whether it could pay
-(§3). The rest of this page is the four things a game gets wrong when nobody tells it.
-
-## 1. The answer is usually no, and no is ordinary
-
-`outcome` is one of exactly three values:
-
-| outcome       | what happened                          | what your game does                      |
-| ------------- | -------------------------------------- | ---------------------------------------- |
-| `no_ad`       | nothing was shown                      | carry on exactly as if you had not asked |
-| `shown`       | a panel was painted and has closed     | carry on — and grant nothing             |
-| `unavailable` | the Arcade could not draw one just now | carry on; read it identically to `no_ad` |
-
-**`no_ad` is the common answer**, not an edge case. There may be nothing suitable, the player may
-be somebody the Arcade will not interrupt, or the break may simply be too soon after the last one.
-You are not told which, and there is nothing to infer.
-
-So write the `no_ad` path as your ordinary path:
-
-- Do **not** render a placeholder, a spinner, or a "nothing to show right now" message. Empty means
-  nothing appears.
-- Do **not** hold up your own flow waiting for a fill. Ask, and continue when the promise settles.
-- Do **not** retry on a no. A second ask at the same break gets the same answer and spends a slot.
-
-**A rewarded ask reads differently, because the player pressed your button and is waiting on it.**
-Its `no_ad` can arrive with the reward already granted (§3), so branch on your inventory, never on
-the outcome; and where nothing landed, a neutral line in your own UI — "No revive this time" — is
-right, with no reason given. (When no ad was available and nothing was granted, the Arcade has
-already shown "No ad available right now" itself.) Draw the button only when
-`gem.ads.rewardedStatus` says it can pay (§3); [`rewarded-ads.md`
-§5](rewarded-ads.md#5-draw-the-button-only-when-it-can-pay) is that button.
-
-## 2. Nothing rejects
-
-`requestAd` always resolves. There is no error branch and no `try`/`catch` to write. Even a refusal
-of your own arguments — a `placement` outside the grammar below, a `format` outside the two —
-resolves `no_ad`, and so does a rewarded ask made without the player's press (see
-[Where to put the call](#where-to-put-the-call)), so your game keeps exactly one branch. (The
-mistake is still reported to your `onError` handler, so you find out in development.)
-
-## 3. ⚠️ `shown` grants nothing
-
-`shown` says a panel was painted and has closed. It is **not** a receipt, **not** an entitlement,
-and **not** permission to hand anything out.
-
-That holds for `format: 'rewarded'` too, the one format that pays the player. The platform grants a
-rewarded placement's reward itself, against its own record of the ad the Arcade played and how it
-ended — never your game, by reading an outcome. An outcome travels over the same channel as
-everything else your frame receives, and a game that unlocks a level or grants a currency on the
-strength of one has an unlock that any page embedding your game can forge.
-
-Treat a break as a break. If your game wants to give the player something for reaching the end of a
-level, give it to them for reaching the end of the level.
-
-**Where a rewarded grant arrives.** On your game's own inventory for this player, written by the
-platform — never by your game — and read through `gem.me.inventory`, the same place a purchase
-lands, read the same way. (That is the game-scoped inventory `gem.me` shows you, not the player's
-platform wallet.) There is **no fourth outcome and no extra field** on the answer. `outcome` is
-pinned at three values because a new value would break every game bundle already in the field: its
-validator refuses the whole message. A new field would not break anything — validators ignore
-fields they do not know — but it is not coming either: anything on that answer can be forged by the
-page embedding your game, so a reward carried there would be a reward anyone could hand out. So
-re-read your snapshot once a rewarded ask settles, whatever it settled as:
-
-```js
-await gem.ads.requestAd({ placement: 'run-banked', 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
-```
-
-A `no_ad` can come back with the reward already in that snapshot, because the platform grants
-without an ad in some cases, so branch on the inventory and never on the outcome. And a reward that
-an ad provider confirms from its own server can land after this re-read, so read again when the
-screen that spends it opens; [`inventory-and-catalogs.md`
-§6](inventory-and-catalogs.md#6-when-to-re-read) is the general form of this.
-[`rewarded-ads.md`](rewarded-ads.md) is the rest: declaring what a placement grants, spending it,
-drawing the button, and testing.
-
-**Whether a rewarded button could pay right now.** A rewarded placement is a button the player
-presses, so you need to know whether to draw it. `gem.ads.rewardedStatus(placement)` reads one
-placement's state from **your own** `rewarded_placements` config — its daily cap, cooldown and
-`max_held` — applied to this player's use of it:
-
-```js
-const status = await gem.ads.rewardedStatus('run-banked');
-bankButton.disabled = !status.grantable;
-```
-
-| field              | what it says                                                               |
-| ------------------ | -------------------------------------------------------------------------- |
-| `declared`         | the config promoted to the channel being played names this placement       |
-| `grantable`        | pressing the button could pay right now — **not** that an ad will play     |
-| `remainingToday`   | grants left today under the daily cap; absent when the placement has none  |
-| `nextEligibleAt`   | when a running cooldown ends, in epoch milliseconds; absent when none runs |
-| `heldLimitReached` | the player already holds the placement's `max_held` — spend one first      |
-| `resetsAt`         | when today's count resets, the next 00:00 UTC, in epoch milliseconds       |
-
-**`grantable` is not a promise.** A player can press a `grantable` button and get `no_ad`, for
-reasons your game is not told. Read that `no_ad` like any other (§1) — never guess a reason — and
-re-read your inventory whatever the ask settled as. The status grants nothing and reserves
-nothing.
-
-It never rejects, like the rest of `gem.ads`. Without a play token, when the read fails or takes
-longer than ten seconds, or for a placement outside the grammar below, it answers not declared and
-not grantable with no `resetsAt`, and the reason goes to your `onError` handler. It is a read of
-the platform, so call it when you draw the button — on a results or death screen — and not every
-frame, and draw the rest of the screen first rather than holding it on the answer.
-
-## 4. The Arcade pauses your game for you
-
-While a panel is up, your game is paused the same way it is paused when a player switches tabs —
-the Arcade sends the pause your game already handles, and lifts it when the panel closes. You do
-not need to pause anything yourself, and you should not resume on a timer: resume when the promise
-settles.
-
-If you have not wired the pause at all yet, that is the thing to fix first;
-[`what-a-game-must-do.md`](what-a-game-must-do.md) covers it.
-
-## Where to put the call
-
-At a break **the player already expects**: a level ending, a round finishing, a run being banked, a
-return to a menu. Never mid-input, never during a timed sequence, and never on a screen the player
-reached by accident.
-
-**A rewarded ask comes from the player's press, and from nowhere else.** Your button is the
-player's opt-in. The Arcade starts the ad as soon as the ask arrives, with no prompt of its own
-first, so an ask the player did not make is an ad they did not choose. Call `requestAd` from the
-button's own `click`, `pointerup`, `touchend` or `keydown` handler, or straight from the
-controller press that chose it. Ask first, before any `await` or timer that could outlast the
-press: a browser counts a tap, click or key press for only a few seconds, and the SDK counts a
-controller press for one.
-
-⚠️ **Not from `pointerdown` or `touchstart`.** On a touchscreen they run before the browser counts
-the tap, so the ask is refused on a phone. With a mouse, `pointerdown` counts, so a desk test passes
-and hides it.
-
-Where the browser reports user activation, your frame holds none, and no controller was used in
-the last second, the SDK answers `no_ad` without asking. It writes a `[gem] rewarded_requires_user_gesture` line to the console once, and
-calls your `onError` handler with code `'internal'` and a message that begins
-`rewarded_requires_user_gesture`, which is the one to match in your own error reporting:
-
-```js
-const gem = createGem({
-  onError: (code, message) => {
-    if (message?.startsWith('rewarded_requires_user_gesture')) {
-      reportBug('rewarded ask outside a press', message); // your own telemetry
-    }
-  },
-});
-```
-
-Where the browser cannot tell, the ask goes ahead. The check is there to catch a mistake while you
-build; it is not a control. It catches an ask with no recent input, and cannot tell which input
-caused the ask, so an ask from another button's handler goes through. An interstitial needs no
-press.
-
-**The button says it is an ad, and names the reward:** "Watch an ad for 3 dice rolls", "Watch an ad
-to revive". Never use a label that hides the ad, or one that reads as the only way forward, such as
-"Tap to continue". [`rewarded-ads.md` §5](rewarded-ads.md#5-draw-the-button-only-when-it-can-pay)
-covers the button.
-
-`placement` is your own name for that break — `level-complete`, `run-banked`, `back-to-menu`. For
-an interstitial, the platform matches it against nothing, never shows it to a player, and does not
-vary its decision on it; it exists so your own analytics can tell two break points apart, so name
-it for yourself. For `format: 'rewarded'`, the placement names the reward your game config declares
-in `rewarded_placements`, and the platform matches it against that config. Either way it **never
-reaches an ad network**, and neither does any other string your game writes.
-
-**It has a grammar, and it is narrow on purpose: 1 to 32 characters of `a-z`, `0-9`, `-` and `_`.**
-Lowercase, no spaces, no accents — `'Boss Fight'` is not a placement, `'boss-fight'` is. Anything
-else resolves `no_ad` and is reported to your `onError` handler, so you meet it while you are
-building rather than later. The platform holds the same grammar where it reads the name: for a
-rewarded ask the Arcade forwards the placement unchanged, and a config that declares one outside
-the grammar is refused at upload, so a name that did not fit would be a reward your shipped game
-could never reach. The bound is the platform's, not the SDK's, and the two agree.
-
-```js
-async function onLevelComplete() {
-  showResultsScreen();
-  await gem.ads.requestAd({ placement: 'level-complete', format: 'interstitial' });
-  // Settled either way. The results screen is still up; the player taps Next.
-  enableNextButton();
-}
-```
-
-## What never crosses
-
-Your game never learns what was shown — no title, no image, no id, nothing about the other game.
-You receive an outcome and nothing else.
-
-You are also never told _why_ the answer was no. That is deliberate and permanent: a reason would
-tell your game something about the player that game code is not told, and there will not be a
-fourth outcome value naming one. The Arcade also settles every `no_ad` and `unavailable` on a
-schedule that does not depend on which branch produced it, so there is nothing in the timing to
-read either. (`shown` is not held back — how long that one takes is how long your player spent
-looking at a panel.)
-
-A rewarded ask is the one case where something else reaches your game: the reward itself, in your
-own inventory, when one was granted. That is what the ask is for. It says that a reward landed,
-never why, so do not read a reason into it.
-
-The other thing you can read is your own economy, and never from the answer:
-`gem.ads.rewardedStatus` reports **your own declared** rewarded caps as the platform holds them —
-the platform can hold a placement's daily cap below what you declared, never above — so you can
-tell when a rewarded `no_ad` was your own cap. It never reports anything about the player, the
-platform's spacing between offers, or any limit that spans games.
-
-## If you do nothing
-
-Nothing happens. A game that never calls `gem.ads.requestAd` is never interrupted, and the call is
-not on the list of things a game must do to ship. This page exists for games that want a break to
-be worth something.