@indiegems/gem-web-sdk 23.1.3 → 23.3.0

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v23.1.3, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v23.3.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -284,6 +284,12 @@ this config server-side; the grant lands on your game's inventory, and
 re-reading `gem.me.inventory` is the only way to learn that it did. Whether
 the button could pay right now is [AdsApi.rewardedStatus](#adsapi-rewardedstatus).
 
+A row may also carry `platform_prices`, the Coin and Gem prices that unlock
+it beside the ad, and `ad: false` when only a price does (`ad` is absent
+otherwise, which means the ad unlocks it). Both are what you declared, not
+what is offered now: label the button from `rewardedStatus`'s
+`adGrantable` and `options`, which say what this platform serves.
+
 Absent when your game declares none.
 
 **Guides.** [rewarded-ads](../rewarded-ads.md)
@@ -3117,6 +3123,7 @@ fourth.
 - `declined` — the player closed the prompt, or the arcade chose not to show
   one. Return to the game silently.
 - `unavailable` — the arcade could not offer sign-in, or never answered.
+  [AccountApi.signInAvailable](#accountapi-signinavailable) says so before you draw the button.
 
 No reason is given for a `declined`, and one will never be added: why a
 sign-in did not happen is a fact about the player's account, and the arcade
@@ -3156,6 +3163,59 @@ interface AccountApi
 
 The account surface. `gem.account` is one of these.
 
+<a id="accountapi-signinavailable"></a>
+
+## AccountApi.signInAvailable
+
+```ts
+readonly signInAvailable: boolean
+```
+
+Whether [AccountApi.requestSignIn](#accountapi-requestsignin) can show this player a sign-in
+here. Read it before you draw a "Sign in to claim" button, and hide the
+offer when it is `false`.
+
+- `true` — a guest the arcade can offer sign-up to. An ask may still
+  answer `declined` at a busy moment.
+- `false` — an ask would show nothing. The player is already signed in
+  (it answers `signed_in` at once; every player in a current Gem Arcade
+  app build, v3.33.174 and later, is), or there is no Arcade sign-in here
+  (it answers `unavailable`). Also `false` until the player is known.
+
+On an arcade older than this signal it reads `true` for every player, a
+full account included, as before it existed. So gate a sign-up gift on it
+and on the guest test you use today; see docs/player-sign-in.md.
+[AccountApi.onSignInAvailableChange](#accountapi-onsigninavailablechange) tells you when it changes.
+
+```ts
+const draw = (available: boolean) => {
+  signInButton.hidden = !available;
+};
+draw(gem.account.signInAvailable);
+gem.account.onSignInAvailableChange(draw);
+```
+
+**Guides.** [player-sign-in](../player-sign-in.md)
+
+<a id="accountapi-onsigninavailablechange"></a>
+
+## AccountApi.onSignInAvailableChange
+
+```ts
+onSignInAvailableChange(listener: (available: boolean) => void): () => void
+```
+
+Runs `listener` whenever [AccountApi.signInAvailable](#accountapi-signinavailable) changes: when
+the player arrives, when the arcade changes its answer (a guest who signs
+up), and when the connection closes. Not on a re-sent player with the same
+answer.
+
+| Parameter | Type |
+| --- | --- |
+| `listener` | `(available: boolean) => void` |
+
+**Returns.** A function that stops the listener.
+
 <a id="accountapi-requestsignin"></a>
 
 ## AccountApi.requestSignIn
@@ -3419,6 +3479,13 @@ means the platform would grant if an ad is watched or, where no ad serves,
 under the placement's `without_ads: grant`; a player can still press the
 button and get `no_ad`, for reasons your game is not told.
 
+A placement your config also prices in Coins or Gems (`platform_prices`)
+carries those prices in `options`, where the platform lets players pay for
+one, and `adGrantable` says whether the ad itself could pay. Label your
+button from both: name the ad only when `adGrantable` is `true`, and each
+price in `options`. The Arcade then shows the player those choices when
+they press, and the press answers and is re-read exactly as an ad's is.
+
 NOTHING REJECTS, like everything else on `gem.ads`. Without a play token,
 when the read fails or takes longer than ten seconds, or for a `placement`
 outside the grammar [AdRequest.placement](#adrequest-placement) documents, it resolves not
@@ -3450,6 +3517,52 @@ if (status.nextEligibleAt !== undefined) {
 
 **Guides.** [rewarded-ads](../rewarded-ads.md)
 
+<a id="rewardedoption"></a>
+
+## RewardedOption
+
+```ts
+interface RewardedOption
+```
+
+One price that also unlocks a rewarded placement, in
+[RewardedStatus.options](#rewardedstatus-options): what your config's `platform_prices` set for
+it, as the platform serves it. Label your button from it ("5 Gems").
+
+It says nothing about the player: not their balance, and not whether they
+can afford it. The Arcade shows them that when they press.
+
+<a id="rewardedoption-kind"></a>
+
+## RewardedOption.kind
+
+```ts
+readonly kind: "coins" | "gems"
+```
+
+Which platform currency: `coins` (Coins, `ARCADE_TICKETS`) or `gems`
+(Gems, `GEMS`).
+
+<a id="rewardedoption-currencyid"></a>
+
+## RewardedOption.currencyId
+
+```ts
+readonly currencyId: string
+```
+
+The platform currency's id, as your config's `platform_prices` resolved it.
+
+<a id="rewardedoption-price"></a>
+
+## RewardedOption.price
+
+```ts
+readonly price: number
+```
+
+The price, a positive whole number of the currency.
+
 <a id="rewardedstatus"></a>
 
 ## RewardedStatus
@@ -3495,12 +3608,48 @@ readonly grantable: boolean
 
 Whether pressing your button could pay right now: the platform would grant
 the reward if an ad is watched or, where no ad serves, under the
-placement's `without_ads: grant`.
+placement's `without_ads: grant` — or, where [RewardedStatus.options](#rewardedstatus-options)
+is present, if the player pays one of its prices.
+
+**Not a promise that an ad will play, and not a promise of a reward.** For
+the ad, it is `false` whenever a cap is spent, a cooldown is running, the
+player holds `max_held`, rewarded is off on this channel, or the arcade
+running your game does not take ad requests at all. The cap, the cooldown
+and `max_held` limit the ad only: a placement with `options` stays
+grantable through them, because the player can still pay. It never says
+whether the player can afford a price.
+
+<a id="rewardedstatus-adgrantable"></a>
+
+## RewardedStatus.adGrantable
+
+```ts
+readonly adGrantable: boolean
+```
+
+Whether the AD could pay right now: [RewardedStatus.grantable](#rewardedstatus-grantable) for
+the ad alone, leaving out the prices. Name the ad on your button only when
+this is `true`.
+
+The same as `grantable` for a placement with no `options`. `false` for a
+placement whose config switches the ad off (`ad: false`) where the
+platform lets players pay for it, and on every answer where `grantable` is.
+
+<a id="rewardedstatus-options"></a>
+
+## RewardedStatus.options
+
+```ts
+readonly options?: readonly RewardedOption[]
+```
+
+The Coin and Gem prices that also unlock the placement, from your config's
+`platform_prices`, at most one per currency.
 
-**Not a promise that an ad will play, and not a promise of a reward.** It
-is `false` whenever a cap is spent, a cooldown is running, the player holds
-`max_held`, rewarded is off on this channel, or the arcade running your
-game does not take ad requests at all.
+ABSENT — no key — for a placement with no prices, on any answer where
+`declared` is `false`, and wherever the platform does not yet let players
+pay for a placement: there your prices are not offered and the placement
+unlocks by its ad alone. Nothing here says what the player holds.
 
 <a id="rewardedstatus-remainingtoday"></a>
 
@@ -3903,7 +4052,8 @@ dimension for it on the events you want to break down, with the arms as its
 values, named after the experiment, and pass the selection there yourself:
 `gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.
 Never the platform's `variant` field, which belongs to store-page
-experiments.
+experiments. For the platform's results to show the test, also declare it
+under `analytics_tests` in your game config (see docs/analytics.md).
 
 WAITS FOR THE PLAYER. The id arrives with the first play token, so a call
 during boot waits for it, and rejects as [Gem.awaitIdentity](#gem-awaitidentity) does

package/docs/api/api-reference-server.md

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v23.1.3, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v23.3.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "23.1.3"
+    "version": "23.3.0"
   },
   "entries": [
     {
@@ -397,7 +397,7 @@
           "group": "config",
           "signature": "rewarded_placements?: SnapshotRewardedPlacement[]",
           "documented": true,
-          "summary": "Your rewarded placements — what pressing a rewarded button grants. An\narray, one row per placement, each naming itself in `placement`, with its\n`grants`, the caps the platform enforces on it (`max_per_day`,\n`cooldown_seconds`, `max_held`) and what happens where no ad serves\n(`without_ads`, which is `nothing` when the config leaves it out).\n\nRead it to LABEL your button — \"+1 Revive\" — never to decide a reward. A\ngrant is an `item_grant`, with a `quantity` of the item its\n`item_definition_id` names, or a `currency_grant`, with an `amount` of the\ncurrency its `currency_id` names; the word on the button is that\ndefinition's `display_name`, from [GameConfig.item](api-reference-game.md#gameconfig-item) or\n[GameConfig.currency](api-reference-game.md#gameconfig-currency):\n\n```js\nconst row = config?.rewarded_placements?.find((p) => p.placement === 'classic_revive');\nconst grant = row?.grants[0];\nconst label =\n  grant?.type === 'item_grant'\n    ? `+${grant.quantity} ${config.item(grant.item_definition_id)?.display_name ?? ''}`\n    : grant?.type === 'currency_grant'\n      ? `+${grant.amount} ${config.currency(grant.currency_id)?.display_name ?? ''}`\n      : undefined;\n```\n\nWhether an ask grants anything is the platform's decision, made against\nthis config server-side; the grant lands on your game's inventory, and\nre-reading `gem.me.inventory` is the only way to learn that it did. Whether\nthe button could pay right now is [AdsApi.rewardedStatus](api-reference-game.md#adsapi-rewardedstatus).\n\nAbsent when your game declares none.",
+          "summary": "Your rewarded placements — what pressing a rewarded button grants. An\narray, one row per placement, each naming itself in `placement`, with its\n`grants`, the caps the platform enforces on it (`max_per_day`,\n`cooldown_seconds`, `max_held`) and what happens where no ad serves\n(`without_ads`, which is `nothing` when the config leaves it out).\n\nRead it to LABEL your button — \"+1 Revive\" — never to decide a reward. A\ngrant is an `item_grant`, with a `quantity` of the item its\n`item_definition_id` names, or a `currency_grant`, with an `amount` of the\ncurrency its `currency_id` names; the word on the button is that\ndefinition's `display_name`, from [GameConfig.item](api-reference-game.md#gameconfig-item) or\n[GameConfig.currency](api-reference-game.md#gameconfig-currency):\n\n```js\nconst row = config?.rewarded_placements?.find((p) => p.placement === 'classic_revive');\nconst grant = row?.grants[0];\nconst label =\n  grant?.type === 'item_grant'\n    ? `+${grant.quantity} ${config.item(grant.item_definition_id)?.display_name ?? ''}`\n    : grant?.type === 'currency_grant'\n      ? `+${grant.amount} ${config.currency(grant.currency_id)?.display_name ?? ''}`\n      : undefined;\n```\n\nWhether an ask grants anything is the platform's decision, made against\nthis config server-side; the grant lands on your game's inventory, and\nre-reading `gem.me.inventory` is the only way to learn that it did. Whether\nthe button could pay right now is [AdsApi.rewardedStatus](api-reference-game.md#adsapi-rewardedstatus).\n\nA row may also carry `platform_prices`, the Coin and Gem prices that unlock\nit beside the ad, and `ad: false` when only a price does (`ad` is absent\notherwise, which means the ad unlocks it). Both are what you declared, not\nwhat is offered now: label the button from `rewardedStatus`'s\n`adGrantable` and `options`, which say what this platform serves.\n\nAbsent when your game declares none.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -3929,7 +3929,7 @@
           "group": "account",
           "signature": "type SignInOutcomeKind = \"signed_in\" | \"declined\" | \"unavailable\"",
           "documented": true,
-          "summary": "The complete vocabulary of answers. Three values, and there will not be a\nfourth.\n\n- `signed_in` — the player is signed in, and [Gem.identity](api-reference-game.md#gem-identity),\n  [Gem.player](api-reference-game.md#gem-player) and [Gem.me](api-reference-game.md#gem-me) already answer for their account.\n  Re-read anything you loaded before asking. Also the answer for a player who\n  was signed in all along.\n- `declined` — the player closed the prompt, or the arcade chose not to show\n  one. Return to the game silently.\n- `unavailable` — the arcade could not offer sign-in, or never answered.\n\nNo reason is given for a `declined`, and one will never be added: why a\nsign-in did not happen is a fact about the player's account, and the arcade\nis the one that explains those.",
+          "summary": "The complete vocabulary of answers. Three values, and there will not be a\nfourth.\n\n- `signed_in` — the player is signed in, and [Gem.identity](api-reference-game.md#gem-identity),\n  [Gem.player](api-reference-game.md#gem-player) and [Gem.me](api-reference-game.md#gem-me) already answer for their account.\n  Re-read anything you loaded before asking. Also the answer for a player who\n  was signed in all along.\n- `declined` — the player closed the prompt, or the arcade chose not to show\n  one. Return to the game silently.\n- `unavailable` — the arcade could not offer sign-in, or never answered.\n  [AccountApi.signInAvailable](api-reference-game.md#accountapi-signinavailable) says so before you draw the button.\n\nNo reason is given for a `declined`, and one will never be added: why a\nsign-in did not happen is a fact about the player's account, and the arcade\nis the one that explains those.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -3986,6 +3986,50 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "AccountApi.signInAvailable",
+          "name": "signInAvailable",
+          "anchor": "accountapi-signinavailable",
+          "group": "account",
+          "signature": "readonly signInAvailable: boolean",
+          "documented": true,
+          "summary": "Whether [AccountApi.requestSignIn](api-reference-game.md#accountapi-requestsignin) can show this player a sign-in\nhere. Read it before you draw a \"Sign in to claim\" button, and hide the\noffer when it is `false`.\n\n- `true` — a guest the arcade can offer sign-up to. An ask may still\n  answer `declined` at a busy moment.\n- `false` — an ask would show nothing. The player is already signed in\n  (it answers `signed_in` at once; every player in a current Gem Arcade\n  app build, v3.33.174 and later, is), or there is no Arcade sign-in here\n  (it answers `unavailable`). Also `false` until the player is known.\n\nOn an arcade older than this signal it reads `true` for every player, a\nfull account included, as before it existed. So gate a sign-up gift on it\nand on the guest test you use today; see docs/player-sign-in.md.\n[AccountApi.onSignInAvailableChange](api-reference-game.md#accountapi-onsigninavailablechange) tells you when it changes.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": "```ts\nconst draw = (available: boolean) => {\n  signInButton.hidden = !available;\n};\ndraw(gem.account.signInAvailable);\ngem.account.onSignInAvailableChange(draw);\n```",
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "player-sign-in",
+              "anchor": null
+            }
+          ]
+        },
+        {
+          "id": "AccountApi.onSignInAvailableChange",
+          "name": "onSignInAvailableChange",
+          "anchor": "accountapi-onsigninavailablechange",
+          "group": "account",
+          "signature": "onSignInAvailableChange(listener: (available: boolean) => void): () => void",
+          "documented": true,
+          "summary": "Runs `listener` whenever [AccountApi.signInAvailable](api-reference-game.md#accountapi-signinavailable) changes: when\nthe player arrives, when the arcade changes its answer (a guest who signs\nup), and when the connection closes. Not on a re-sent player with the same\nanswer.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "listener",
+              "type": "(available: boolean) => void",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "A function that stops the listener.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "AccountApi.requestSignIn",
           "name": "requestSignIn",
@@ -4170,7 +4214,7 @@
           "group": "ads",
           "signature": "rewardedStatus(placement: string): Promise<RewardedStatus>",
           "documented": true,
-          "summary": "Whether a rewarded placement could pay right now, so you can decide whether\nto draw its button. **It never says whether an ad will play.**\n\nThe answer comes from your own `rewarded_placements` config — its daily\ncap, cooldown and `max_held` — applied to this player's use of it, as the\nplatform holds them. Nothing in it describes the player. `grantable: true`\nmeans the platform would grant if an ad is watched or, where no ad serves,\nunder the placement's `without_ads: grant`; a player can still press the\nbutton and get `no_ad`, for reasons your game is not told.\n\nNOTHING REJECTS, like everything else on `gem.ads`. Without a play token,\nwhen the read fails or takes longer than ten seconds, or for a `placement`\noutside the grammar [AdRequest.placement](api-reference-game.md#adrequest-placement) documents, it resolves not\ndeclared and not grantable, with no `resetsAt`, and the reason goes to your\n`onError` handler.\n\nIt is a read of the platform, so call it when you draw the button — on a\nresults or death screen — not every frame. Calls for one placement that\noverlap share one request. Draw the rest of the screen first rather than\nholding it on this answer.\n\n⚠️ It grants nothing and reserves nothing. The reward is granted by the\nplatform when the player asks with `requestAd`; re-read `gem.me.inventory`\nafter that ask settles, whatever it settled as.",
+          "summary": "Whether a rewarded placement could pay right now, so you can decide whether\nto draw its button. **It never says whether an ad will play.**\n\nThe answer comes from your own `rewarded_placements` config — its daily\ncap, cooldown and `max_held` — applied to this player's use of it, as the\nplatform holds them. Nothing in it describes the player. `grantable: true`\nmeans the platform would grant if an ad is watched or, where no ad serves,\nunder the placement's `without_ads: grant`; a player can still press the\nbutton and get `no_ad`, for reasons your game is not told.\n\nA placement your config also prices in Coins or Gems (`platform_prices`)\ncarries those prices in `options`, where the platform lets players pay for\none, and `adGrantable` says whether the ad itself could pay. Label your\nbutton from both: name the ad only when `adGrantable` is `true`, and each\nprice in `options`. The Arcade then shows the player those choices when\nthey press, and the press answers and is re-read exactly as an ad's is.\n\nNOTHING REJECTS, like everything else on `gem.ads`. Without a play token,\nwhen the read fails or takes longer than ten seconds, or for a `placement`\noutside the grammar [AdRequest.placement](api-reference-game.md#adrequest-placement) documents, it resolves not\ndeclared and not grantable, with no `resetsAt`, and the reason goes to your\n`onError` handler.\n\nIt is a read of the platform, so call it when you draw the button — on a\nresults or death screen — not every frame. Calls for one placement that\noverlap share one request. Draw the rest of the screen first rather than\nholding it on this answer.\n\n⚠️ It grants nothing and reserves nothing. The reward is granted by the\nplatform when the player asks with `requestAd`; re-read `gem.me.inventory`\nafter that ask settles, whatever it settled as.",
           "deprecated": null,
           "params": [
             {
@@ -4191,6 +4235,70 @@
             }
           ]
         },
+        {
+          "id": "RewardedOption",
+          "name": "RewardedOption",
+          "anchor": "rewardedoption",
+          "group": "ads",
+          "signature": "interface RewardedOption",
+          "documented": true,
+          "summary": "One price that also unlocks a rewarded placement, in\n[RewardedStatus.options](api-reference-game.md#rewardedstatus-options): what your config's `platform_prices` set for\nit, as the platform serves it. Label your button from it (\"5 Gems\").\n\nIt says nothing about the player: not their balance, and not whether they\ncan afford it. The Arcade shows them that when they press.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedOption.kind",
+          "name": "kind",
+          "anchor": "rewardedoption-kind",
+          "group": "ads",
+          "signature": "readonly kind: \"coins\" | \"gems\"",
+          "documented": true,
+          "summary": "Which platform currency: `coins` (Coins, `ARCADE_TICKETS`) or `gems`\n(Gems, `GEMS`).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedOption.currencyId",
+          "name": "currencyId",
+          "anchor": "rewardedoption-currencyid",
+          "group": "ads",
+          "signature": "readonly currencyId: string",
+          "documented": true,
+          "summary": "The platform currency's id, as your config's `platform_prices` resolved it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedOption.price",
+          "name": "price",
+          "anchor": "rewardedoption-price",
+          "group": "ads",
+          "signature": "readonly price: number",
+          "documented": true,
+          "summary": "The price, a positive whole number of the currency.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "RewardedStatus",
           "name": "RewardedStatus",
@@ -4230,7 +4338,39 @@
           "group": "ads",
           "signature": "readonly grantable: boolean",
           "documented": true,
-          "summary": "Whether pressing your button could pay right now: the platform would grant\nthe reward if an ad is watched or, where no ad serves, under the\nplacement's `without_ads: grant`.\n\n**Not a promise that an ad will play, and not a promise of a reward.** It\nis `false` whenever a cap is spent, a cooldown is running, the player holds\n`max_held`, rewarded is off on this channel, or the arcade running your\ngame does not take ad requests at all.",
+          "summary": "Whether pressing your button could pay right now: the platform would grant\nthe reward if an ad is watched or, where no ad serves, under the\nplacement's `without_ads: grant` — or, where [RewardedStatus.options](api-reference-game.md#rewardedstatus-options)\nis present, if the player pays one of its prices.\n\n**Not a promise that an ad will play, and not a promise of a reward.** For\nthe ad, it is `false` whenever a cap is spent, a cooldown is running, the\nplayer holds `max_held`, rewarded is off on this channel, or the arcade\nrunning your game does not take ad requests at all. The cap, the cooldown\nand `max_held` limit the ad only: a placement with `options` stays\ngrantable through them, because the player can still pay. It never says\nwhether the player can afford a price.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.adGrantable",
+          "name": "adGrantable",
+          "anchor": "rewardedstatus-adgrantable",
+          "group": "ads",
+          "signature": "readonly adGrantable: boolean",
+          "documented": true,
+          "summary": "Whether the AD could pay right now: [RewardedStatus.grantable](api-reference-game.md#rewardedstatus-grantable) for\nthe ad alone, leaving out the prices. Name the ad on your button only when\nthis is `true`.\n\nThe same as `grantable` for a placement with no `options`. `false` for a\nplacement whose config switches the ad off (`ad: false`) where the\nplatform lets players pay for it, and on every answer where `grantable` is.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.options",
+          "name": "options",
+          "anchor": "rewardedstatus-options",
+          "group": "ads",
+          "signature": "readonly options?: readonly RewardedOption[]",
+          "documented": true,
+          "summary": "The Coin and Gem prices that also unlock the placement, from your config's\n`platform_prices`, at most one per currency.\n\nABSENT — no key — for a placement with no prices, on any answer where\n`declared` is `false`, and wherever the platform does not yet let players\npay for a placement: there your prices are not offered and the placement\nunlocks by its ad alone. Nothing here says what the player holds.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -4639,7 +4779,7 @@
           "group": "analytics",
           "signature": "experiment(key: string, count: number): Promise<number>",
           "documented": true,
-          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n[experimentSelection](api-reference-game.md#experimentselection), which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments.\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as [Gem.awaitIdentity](api-reference-game.md#gem-awaitidentity) does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
+          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n[experimentSelection](api-reference-game.md#experimentselection), which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments. For the platform's results to show the test, also declare it\nunder `analytics_tests` in your game config (see docs/analytics.md).\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as [Gem.awaitIdentity](api-reference-game.md#gem-awaitidentity) does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
           "deprecated": null,
           "params": [
             {
@@ -30922,7 +31062,7 @@
           "group": "analytics",
           "signature": "experiment(key: string, count: number): Promise<number>",
           "documented": true,
-          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n`experimentSelection`, which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments.\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as `Gem.awaitIdentity` does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
+          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n`experimentSelection`, which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments. For the platform's results to show the test, also declare it\nunder `analytics_tests` in your game config (see docs/analytics.md).\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as `Gem.awaitIdentity` does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
           "deprecated": null,
           "params": [
             {

package/docs/arcade-and-store.md

@@ -223,7 +223,8 @@ policy refused. Allow that host rather than a wildcard.
 
 ```js
 const { outcome, reason, offers } = await gem.store.offers();
-if (outcome === 'unavailable' && reason === 'sign_in_required') showSignInButton(); // gem.account.requestSignIn
+if (outcome === 'unavailable' && reason === 'sign_in_required' && gem.account.signInAvailable)
+  showSignInButton(); // gem.account.requestSignIn
 for (const offer of offers) drawOffer(offer);
 ```
 
@@ -443,7 +444,8 @@ player, and the route refuses it with `403`. The body is `{ pass, held, ends_at
   or the lounge, and either way nobody got in by editing the page. Redraw the door when the function
   says no.
 - **A guest has no VIP and cannot buy it from here.** Their door is shut, and `offers()` answers
-  `unavailable` / `sign_in_required`, so offer `gem.account.requestSignIn` instead of the button.
+  `unavailable` / `sign_in_required`, so offer `gem.account.requestSignIn` instead of the button,
+  when `gem.account.signInAvailable` says the Arcade can show them a sign-in.
 
 ### When the door moves by itself
 

package/docs/changelog.md

@@ -16,6 +16,36 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 23.3.0
+
+*Written from the API facts alone; no summary was generated for this release.*
+
+Upgrading from 23.2.0. Impact: required.
+
+### Must change
+
+- FrameCallbacks.onPlayer changed its signature.
+- FrameOptions.onPlayer changed its signature.
+
+### New capability
+
+- AccountApi.onSignInAvailableChange was added.
+- AccountApi.signInAvailable was added.
+- GemPlayer.signInAvailable was added.
+- SendPlayerInput.signInAvailable was added.
+
+## 23.2.0
+
+*Written from the API facts alone; no summary was generated for this release.*
+
+Upgrading from 23.1.3. Impact: none.
+
+### New capability
+
+- RewardedOption was added.
+- RewardedStatus.adGrantable was added.
+- RewardedStatus.options was added.
+
 ## 23.1.3
 
 Upgrading from 23.1.2. Impact: none.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "23.1.3"
+  "@indiegems/gem-web-sdk": "23.3.0"
 }
 ```
 

package/docs/manifest.json

@@ -13,13 +13,13 @@
     },
     {
       "file": "analytics.md",
-      "sha256": "5814655859e3d6b223f94b71f1b064783b0f242d409c3ec3078089cb4b7c8ec5",
-      "updated": "2026-11-04T17:17:14Z"
+      "sha256": "3f81025a763f96d0ca17f57377042a3e3890797983265cdb1721902b700aa3a6",
+      "updated": "2026-11-09T18:54:26Z"
     },
     {
       "file": "arcade-and-store.md",
-      "sha256": "79bd7829d5a6577d3619d7fd831b74065df883e11eadd1b8153754d97a88474a",
-      "updated": "2026-11-02T18:42:37Z"
+      "sha256": "5b880e515ce0d65ffff77b97c93844dbcc14d7ab55d89edabaa54f4858376216",
+      "updated": "2026-11-09T16:45:36Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "e6195c6d12e52535a21a4a3291268a82a445b85e6a76f0049b981ff9ab374232",
-      "updated": "2026-11-09T03:45:00Z"
+      "sha256": "85e888011b15aa2e9ebb56d938b9a8165489167bcebda236cba9e4f09937044f",
+      "updated": "2026-11-10T15:57:23Z"
     },
     {
       "file": "daily-challenges.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "aaed9165f80ea79b32eae8509dc2ef0af436b3e3df1d23cac30941c8268ee022",
-      "updated": "2026-11-09T03:45:00Z"
+      "sha256": "bdadeee9b46529d4ef9543a2be61cd096e6b200c20dbe2ab1b361d23139d3e64",
+      "updated": "2026-11-10T15:57:23Z"
     },
     {
       "file": "graphics-route.md",
@@ -118,13 +118,13 @@
     },
     {
       "file": "player-sign-in.md",
-      "sha256": "22c798ff32ee15dda88f08f6701146f83fe92568c737d9321edd3e2550cb2df9",
-      "updated": "2026-11-09T02:37:14Z"
+      "sha256": "f5066f2382bac9336c697d3646843f546295686a959726e877431ec7dc2daea3",
+      "updated": "2026-11-09T18:39:56Z"
     },
     {
       "file": "rewarded-ads.md",
-      "sha256": "81b421d4bde3f71b40c7a5a173e6a2c114a315215a11491e488872ff9e1909dc",
-      "updated": "2026-11-07T16:40:01Z"
+      "sha256": "36394d5faee67f3907139b1fe8c8210a6074a6eac593bc070b567625e71c6129",
+      "updated": "2026-11-09T19:34:44Z"
     },
     {
       "file": "room-shapes.md",
@@ -143,8 +143,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "3274318b99daed546ee192381e40962c9e1e62436cbf4edfb61340548d6dc493",
-      "updated": "2026-11-09T03:45:00Z"
+      "sha256": "921591332e0a9fc52d36e3372af26a5ea808768e1bbd49826d765b7e4615ab53",
+      "updated": "2026-11-10T15:57:23Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -168,8 +168,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "f70fe9fad67c6b386bddc53f1f876bb78f6a5e11c35f565bb93e925d65a99874",
-      "updated": "2026-11-06T22:48:07Z"
+      "sha256": "c5400f43a1218de0d2838d4332dce4c05afe21ff04e352d2e201ef5bb4268bed",
+      "updated": "2026-11-09T18:39:56Z"
     }
   ]
 }