@indiegems/gem-web-sdk 23.1.3 → 23.3.0

package/docs/player-sign-in.md

@@ -17,8 +17,56 @@ signInButton.onclick = async () => {
 };
 ```
 
-That is the whole surface. Your game never draws a sign-in form and never handles a password; it
-could not be trusted with either, and it does not need to be.
+That is almost the whole surface. Your game never draws a sign-in form and never handles a
+password; it could not be trusted with either, and it does not need to be.
+
+## Before you draw the button
+
+Not every player can be shown a sign-in. Before you draw "Sign in to claim", read
+`gem.account.signInAvailable`, and listen for it to change:
+
+```js
+const drawUpsell = (available) => {
+  signInButton.hidden = !available;
+};
+drawUpsell(gem.account.signInAvailable);
+gem.account.onSignInAvailableChange(drawUpsell);
+```
+
+- **`true`**: pressing the button will normally put the Arcade's sign-in up for this player. It can
+  still answer `declined` at a busy moment, such as while the Arcade has a sheet or a menu open.
+- **`false`**: pressing it would show nothing. Don't draw the offer. Either the player is already
+  signed in (an ask answers `signed_in` at once), or nothing can be shown here (it answers
+  `unavailable`). It is also `false` until the player is known, and again once the game is
+  disconnected.
+
+**In current Gem Arcade app builds (v3.33.174 and later), every player is already signed in.** The
+app signs each player in to a full account: a device account, Play Games or Game Center, or another
+sign-in. So `signInAvailable` is `false` there, and an ask answers `signed_in` at once, with nothing
+shown. Don't draw a sign-in offer in the app. Older app builds run an older Arcade, where the next
+paragraph applies: `signInAvailable` reads `true` there.
+
+On an Arcade older than this signal, `signInAvailable` reads `true` for every player, a full
+account included. That is how a sign-in ask behaved before the signal existed. So a game that reads
+it keeps its button there, and a player who is already signed in and presses it gets `signed_in`
+at once, with nothing shown. Keep handling every answer quietly (section 3).
+
+`onSignInAvailableChange` runs only when the answer changes: when the player arrives, when a guest
+signs up in place, and when the game is disconnected. It returns a function that stops it.
+
+### Gating a sign-up gift
+
+If your game gives a gift for signing up, offer it only while `signInAvailable` is `true`. That
+means a guest the Arcade can sign up here, so you don't need to work out who is a guest from
+`gem.store.offers()` answering `unavailable` / `sign_in_required`.
+
+On an older Arcade the signal can't do that job alone. It reads `true` for every player there, so a
+gift gated on it alone is offered to players who already have an account. Pressing it answers
+`signed_in` at once, which a player who was signed in all along gets too, so that answer is no
+proof of a sign-up either. Your game can't tell which kind of Arcade it is running in, so for now
+gate the gift on both: `signInAvailable` is `true` **and** the guest test you use today, such as
+`offers()` answering `sign_in_required`. On a current Arcade the two agree for a guest. On an older
+one, the second keeps the gift from players who are already signed in.
 
 ## 1. Save before you ask
 
@@ -56,7 +104,7 @@ and nothing has changed; hide the upsell.
 |---|---|---|
 | `signed_in` | the player is signed in | re-read, then hide the upsell |
 | `declined` | the player closed the prompt, or the Arcade chose not to show one | return to the game silently |
-| `unavailable` | the Arcade does not offer this here, or never answered | return to the game silently |
+| `unavailable` | the Arcade does not offer this here, or never answered | return to the game silently; `signInAvailable` was `false` for most of these |
 
 `requestSignIn` always resolves when it resolves at all. There is no error branch and no
 `try`/`catch` to write.

package/docs/rewarded-ads.md

@@ -111,6 +111,8 @@ rewarded_placements:
 | `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`             | **Optional:** `grant` or `nothing`, and `nothing` when you leave it out. What a press gets when no ad plays: where no ad serves your channel at all, and where one does but no ad was available for this press or it failed to play (§8). `grant` pays the reward with no ad, within your caps, so write it out only for a reward that is fine to give free.                                                                                                                                                                                                                  |
 | `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` and must have `transfer_policy: none`. A grant is refused while it is empty (§3). ⚠️ For an allowance your game grants per use, put it in a bucket that never resets (`reset_interval: never`) for now, even though the upload warns `rewarded_placement_allowance_no_reset` (below).                                                                                                            |
+| `ad`                      | **Optional:** `true` or `false`, and `true` when you leave it out. Whether watching an ad unlocks the placement. Write `false` only beside `platform_prices`, for a placement a price alone unlocks.                                                                                                                                                                                                                                                                                                                                                                          |
+| `platform_prices`         | **Optional:** Coin and Gem prices that also unlock the placement, beside the ad or instead of it, written as an item's prices are. Leave it out for none. See [Coins and Gems beside the ad](#coins-and-gems-beside-the-ad), below.                                                                                                                                                                                                                                                                                                                                           |
 
 ⚠️ **Until a gem-api fix ships, an allowance in a resetting bucket refuses a player's first
 press.** A grant that creates the player's balance of the allowance currency is not stamped with
@@ -170,6 +172,91 @@ pays without one. If both said `grant`, the bigger reward would cost the player
 everyone would press that button. Leaving it out of the bigger one, which is `nothing`, keeps it a
 reward for watching.
 
+### Coins and Gems beside the ad
+
+A placement can also be unlocked for the player's **Coins** (`ARCADE_TICKETS`) or **Gems** (`GEMS`),
+beside its ad or instead of it. Give it `platform_prices`, the same shape an item's prices take,
+at most one per currency, each a positive whole number:
+
+```yaml
+rewarded_placements:
+  - placement: classic_revive
+    grants:
+      - { type: item_grant, item_definition_slug: revive_token, quantity: 1 }
+    max_per_day: 5 # limits the ad only
+    platform_prices:
+      - { currency: ARCADE_TICKETS, price: 50 } # 50 Coins
+      - { currency: GEMS, price: 5 } # 5 Gems
+  - placement: skip_level
+    grants:
+      - { type: item_grant, item_definition_slug: level_skip, quantity: 1 }
+    ad: false # a price alone unlocks this one
+    platform_prices:
+      - { currency: GEMS, price: 10 }
+```
+
+Your game asks exactly as it does for an ad: `requestAd` from the press (§3), then re-read your
+inventory. The Arcade, not your game, shows the player the choices that press has: a chooser when
+there are several, such as **Watch an ad**, **50 Coins** and **5 Gems**, or a confirmation when a
+price is the only one. A price the player cannot afford is shown but cannot be picked. Paying takes
+the price from the player's wallet and grants the reward in one step: never the reward without the
+payment, never charged twice, and the payment given back if the reward cannot be granted. Nothing
+is bought with real money here. The answer is `shown` whenever the Arcade put a choice up, whatever
+the player then did, so **branch on your inventory, never on the outcome**, as for an ad.
+
+- **Your caps limit the ad only.** `max_per_day`, `cooldown_seconds`, `max_held` and
+  `allowance_currency_slug` decide when the ad can pay. The prices stay on offer when the ad
+  cannot, and a paid unlock does not count toward them. Only the player's balance limits how often
+  they pay, so price the reward for that. The grant still refuses a reward that would not fit
+  (a full stack, say), and the payment is then given back.
+- **Not with `without_ads: grant`,** which would give the reward free and make the price pointless.
+  The upload refuses it, and `ad: false` with no `platform_prices` too, since then nothing unlocks
+  the placement.
+- **Each currency's spend scope applies,** as it does to an item's price
+  ([`inventory-and-catalogs.md`](inventory-and-catalogs.md#what-coins-and-gems-may-buy-the-spend-scope)):
+  where Coins may price cosmetics only, a Coin price on a placement that grants anything else is
+  refused. Gems may price any placement. `gemctl platform config` lists which currencies your
+  game may price in, and each one's spend scope: author against it, never against a list you
+  remember.
+- **A placement's own prices do not make its reward "sold for a platform currency"** in §1's sense,
+  so the ad keeps serving beside them as it did before.
+
+⚠️ **The upload warns `rewarded_paid_unlocks_not_live` while the platform does not let players pay
+for a placement yet.** Until then your prices are not offered, the placement unlocks by its ad
+alone, `ad: false` included, and `rewardedStatus` carries no `options` (§5). Nothing in your game
+needs to change when it goes live: draw the button from `rewardedStatus` and it follows.
+
+### A placement or the store?
+
+Now that a placement can take Coins and Gems, pick by what the player is buying:
+
+- **A single-reward button** (a hint, an extra life, a skip) is a **rewarded placement**, with
+  `platform_prices` for Coins and Gems. Whether it offers the ad, Coins, Gems or any mix is then a
+  config switch (`ad` and `platform_prices`), not code: the button and its `requestAd` stay the
+  same, and the Arcade shows the player the choices.
+- **A real shop** (several items, quantities, locked items) is **store items and recipes** with
+  `platform_prices`
+  ([`inventory-and-catalogs.md`](inventory-and-catalogs.md#16-selling-for-a-platform-currency)).
+  A placement grants one fixed reward per press: it has no list of items, no quantity, and no
+  prerequisite to lock anything behind.
+
+A hint button the player can unlock with an ad or 2 Gems:
+
+```yaml
+rewarded_placements:
+  - placement: hint # exactly the string your game passes
+    grants:
+      - { type: item_grant, item_definition_slug: hint_token, quantity: 1 }
+    max_per_day: 5 # limits the ad only
+    platform_prices:
+      - { currency: GEMS, price: 2 }
+```
+
+Add `{ currency: ARCADE_TICKETS, price: 20 }` beside it for Coins where Coins' spend scope lets
+them price a hint (above), and `ad: false` to drop the ad. Do not also sell `hint_token` in your
+shop: the reward then counts as sold for a platform currency (§1), the upload warns, and outside
+test ads its ad is only served where the platform verifies completion with the ad provider.
+
 ## 3. Ask from the press, then re-read
 
 ```js
@@ -342,14 +429,32 @@ const status = await gem.ads.rewardedStatus('classic_revive');
 watchAdButton.hidden = !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       |
+**For a placement with prices** (§2), `grantable` is `true` when the ad could pay **or** a price
+could, so the button stays up through the ad's caps. Label it from the answer: name the ad only
+when `adGrantable` is `true`, and each price in `options`, whose `kind` is `coins` or `gems`.
+Neither says what the player holds; the Arcade shows that when they press. Both are in SDK
+releases after 23.1.3.
+
+```js
+const status = await gem.ads.rewardedStatus('classic_revive');
+const ways = [
+  ...(status.adGrantable ? ['watch an ad'] : []),
+  ...(status.options ?? []).map((o) => `${o.price} ${o.kind === 'coins' ? 'Coins' : 'Gems'}`),
+];
+reviveButton.textContent = `Revive: ${ways.join(' or ')}`; // "Revive: watch an ad or 5 Gems"
+reviveButton.hidden = !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                     |
+| `adGrantable`      | the ad itself could pay right now: `grantable` without the prices                          |
+| `options`          | the Coin and Gem prices on offer, each `{ kind, currencyId, price }`; absent when none are |
+| `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                       |
 
 Without a play token, when the read fails or takes longer than ten seconds, or for a placement
 outside the grammar, it answers not declared and not grantable with no `resetsAt`, and the reason

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v23.1.3/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v23.1.3/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v23.3.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v23.3.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/docs/what-a-game-must-do.md

@@ -2404,10 +2404,13 @@ Not on the list above either. When a player reaches for something only an accoun
 `gem.account.requestSignIn` asks the Arcade to sign them in, in its own chrome. Your game draws no
 form and passes nothing.
 
-Two things before you reach for it: **save first**, because the Arcade may sign the player in by
-taking the whole page away, and your game then starts again rather than hearing an answer; and on
-`signed_in`, **re-read what you loaded**, because the player underneath your game may not be the
-one who was there a moment ago. [`player-sign-in.md`](player-sign-in.md) is the page.
+Draw the offer only while `gem.account.signInAvailable` is `true`: it is `false` for a player
+already signed in (every player in a current Gem Arcade app build, v3.33.174 and later, is), and
+wherever nothing can be shown. Two
+things before you reach for it: **save first**, because the Arcade may sign the player in by taking
+the whole page away, and your game then starts again rather than hearing an answer; and on `signed_in`, **re-read what you loaded**, because the player
+underneath your game may not be the one who was there a moment ago.
+[`player-sign-in.md`](player-sign-in.md) is the page.
 
 ## A Share button, if your game has something worth sending a friend
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "23.1.3",
+  "version": "23.3.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -840,6 +840,47 @@
               ]
             }
           }
+        },
+        "signInAvailable": {
+          "kind": "boolean",
+          "optional": true,
+          "$comment": [
+            "Whether a `gem.requestSignIn` from a player's press would put the",
+            "Arcade's sign-in prompt up for THIS player HERE.",
+            "The SDK reads it as `gem.account.signInAvailable`, so a game hides a",
+            "\"Sign in to claim\" offer that could show nothing.",
+            "",
+            "`true`: a browser guest on a surface that offers sign-up. An ask can",
+            "still answer `declined` at a busy moment (a sheet, a menu, a parked",
+            "game, a second ask); those holds are momentary and not part of this",
+            "field. `false`: an ask shows nothing — it answers `signed_in` at once",
+            "(a full account, which every player in the Gem Arcade app is) or",
+            "`unavailable` (a garden that offers no sign-up, a surface with no",
+            "sign-in). A parent",
+            "that knows sends it on EVERY `gem.player`, `false` included, and",
+            "re-sends the message when it changes (a guest who signs up in place).",
+            "",
+            "ABSENT means an older parent, and a frame reads it as `true`, which is",
+            "what `gem.requestSignIn` did there before this field: a game that adopts",
+            "it keeps its button on an old host. So a parent must never omit it to",
+            "mean `false`.",
+            "",
+            "A BOOLEAN, NEVER AN ENUM. A new enum value is breaking here: an N-1",
+            "frame's validator would refuse the whole message and cost the game its",
+            "player's name.",
+            "",
+            "Platform-assigned, so it sits outside `untrusted`. Ungated like the rest",
+            "of `gem.player`; it means something only beside the `signIn`",
+            "capability, without which the SDK reads `false` whatever it says.",
+            "",
+            "DISCLOSURE. `true` tells a game \"this is a browser guest\": the fact",
+            "`gem.requestSignIn` already discloses, since a",
+            "full account answers `signed_in` at once and a guest's answer follows a",
+            "person. `false` reveals less: it does not tell a signed-in player from",
+            "a surface with no sign-in. And `gem.player` is withheld until the launch is",
+            "confirmed, so an unconfirmed launch learns nothing. It carries no",
+            "sanction, session or age band."
+          ]
         }
       },
       "rateLimit": { "perMinute": 12 }