@indiegems/gem-web-sdk 8.0.0 → 9.0.0

package/schema/bridge.v1.json

@@ -590,7 +590,7 @@
           "kind": "array",
           "maxItems": 2,
           "optional": true,
-          "$comment": "Equipped badges in display order — empty until platform achievements equip any, and never more than two. Each is an item id and a thumbnail URL, the same pin caveat as `avatarIconUrl`.",
+          "$comment": "Equipped badges in the order the player arranged them — never more than two, and empty when the player wears none. Each is an item id and a thumbnail URL, the same pin caveat as `avatarIconUrl`.",
           "items": {
             "kind": "object",
             "fields": {
@@ -2715,6 +2715,47 @@
       "rateLimit": { "perMinute": 120 }
     },
 
+    {
+      "type": "gem.portraitBorders",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Which of the store page's portrait borders the parent paints beside the",
+        "game while it letterboxes a portrait game on a wide screen. `name` is one",
+        "of the names the page declares under `media.portrait_borders`; absent",
+        "means clear the sides to the parent's own bars, for a theme with no art.",
+        "",
+        "A KEY INTO PUBLISHED ART, NEVER THE ART. The images are the store page's,",
+        "served and reviewed like every other store image; the frame chooses only",
+        "which one and when. The parent looks `name` up by exact match in the list",
+        "the page it is showing declares, and never renders it as text or builds a",
+        "URL from it. A name that list does not hold is ignored and the current",
+        "image stays. Transitions, their timing and any minimum dwell are the",
+        "parent's, swaps wait while a trusted overlay is up, and the frame gets no",
+        "acknowledgement.",
+        "",
+        "`name` is a plain bounded string with no format: a border name may carry",
+        "digits and hyphens, which the `code` format refuses. The SDK sends only",
+        "names matching `^[a-z0-9][a-z0-9_-]{0,39}$`, the store page's own rule, and",
+        "a parent checks the same rule on receipt.",
+        "",
+        "STATE, NOT A MOMENT. The SDK holds the game's latest choice until the",
+        "bridge connects and sends at most one a second, latest wins, so a burst",
+        "(a theme picker previewing on hover) delivers its final value well inside",
+        "the limit below.",
+        "",
+        "Gated by `portraitBorders`, which a parent that paints borders advertises",
+        "to EVERY game on every device, whether or not the game declares borders or",
+        "is letterboxed right now. It is never a signal of form factor or letterbox",
+        "state, and the parent answers nothing, so the frame learns nothing about",
+        "how it is being shown."
+      ],
+      "fields": {
+        "name": { "kind": "string", "maxLength": 40, "optional": true }
+      },
+      "rateLimit": { "perMinute": 60 }
+    },
+
     {
       "type": "gem.error",
       "direction": "both",
@@ -3162,6 +3203,9 @@
         "",
         "  RENDER IT IN YOUR OWN CHROME. Labelled as a promotion, dismissible, and",
         "  focus-trapped over the paused game. Nothing in this message is rendered.",
+        "  For `rewarded`, the player pressed the game's button, and the game's",
+        "  label is not the disclosure: paint an offer sheet that says it is an ad",
+        "  and what the player gets, with a way to decline, BEFORE anything plays.",
         "",
         "  PAUSE WITH `gem.pause`. That message already means 'stop running and stop",
         "  making noise', which is exactly what is wanted while a panel is up. Do",
@@ -3183,10 +3227,14 @@
         "  generated validator checks type and length only - it may carry `../`,",
         "  NUL, newlines, RTL overrides and astral Unicode. The SDK will only SEND",
         "  `^[a-z0-9_-]{1,32}$`, which is the grammar the platform's own ad",
-        "  endpoint accepts - but that is the sender keeping a promise, not a",
-        "  guarantee you hold: a hostile frame posts on the port directly. It is",
-        "  matched against nothing, never interpolated into a path or a log line,",
-        "  and never shown to a player.",
+        "  endpoints accept - but that is the sender keeping a promise, not a",
+        "  guarantee you hold: a hostile frame posts on the port directly. For an",
+        "  interstitial it is matched against nothing. For `rewarded` it is the key",
+        "  of the reward the game's config declares, so check it against that",
+        "  grammar YOURSELF before forwarding it, in a request body, to the",
+        "  platform's rewarded offer. Never interpolate it into a path or an",
+        "  unchecked log line, never show it to a player, and NEVER SEND IT TO AN",
+        "  AD NETWORK: it stops at the platform, as every game-authored string does.",
         "",
         "  THE `perMinute` BELOW BOUNDS A BUGGY GAME, NOT A HOSTILE ONE. A hostile",
         "  game posts on the port it holds rather than calling the SDK, so a",
@@ -3202,12 +3250,12 @@
         "placement": {
           "kind": "string",
           "maxLength": 32,
-          "$comment": "The game's own name for the break it is at - 'level-complete', 'between-rounds'. UNTRUSTED TEXT, MATCHED AGAINST NOTHING BY TODAY'S PARENT: it does not look it up, does not vary its decision on it and does not render it. THE BOUND IS THE PLATFORM'S OWN, not a number chosen here: the ad endpoint behind the arcade accepts `^[a-z0-9_-]{1,32}$` and answers 400 otherwise, so 32 is what this carries and the SDK refuses the charset before sending. A real ad network keys its ad units BY placement - that is what the field is for - so the day one is swapped in the parent starts forwarding this string unchanged, and a game that shipped 'Boss Fight' or a 40-character name would have to be rebuilt. The grammar is narrow NOW, while nothing has shipped against it, so a game learns at development time instead. Codegen emits type and length only; the charset is the sender's to keep."
+          "$comment": "The game's own name for the break it is at - 'level-complete', 'classic_revive'. UNTRUSTED TEXT, never rendered. FOR AN INTERSTITIAL IT IS MATCHED AGAINST NOTHING: the parent does not look it up and does not vary its decision on it. FOR `rewarded` IT NAMES THE REWARD the game's config declares in `rewarded_placements`: the parent forwards it unchanged to the platform's rewarded offer, which matches it against that config, and a placement the config does not declare is answered `no_ad`. IT NEVER REACHES AN AD NETWORK, for either format, because a game-authored string that fits this grammar fits a dashless UUID too and would be an identifier channel to a third party. THE BOUND IS THE PLATFORM'S OWN, not a number chosen here: the platform's ad endpoints accept `^[a-z0-9_-]{1,32}$` and answer 400 otherwise, and config upload holds a declared placement to the same grammar, so 32 is what this carries and the SDK refuses the charset before sending. A game that shipped 'Boss Fight' or a 40-character name would have to be rebuilt to reach its reward, so the SDK refuses it at development time instead. Codegen emits type and length only; the charset is the sender's to keep."
         },
         "format": {
           "kind": "enum",
           "values": ["interstitial", "rewarded"],
-          "$comment": "A closed set, so a typo is refused at the boundary rather than left for the parent to interpret. `rewarded` IS IN THE GRAMMAR AND IS NOT SERVED: it is answered `no_ad` today, and a `shown` would grant nothing even when it is not - see gem.adResult's outcome. A game that grants a reward on an outcome has a reward any page that can post on this port can forge."
+          "$comment": "A closed set, so a typo is refused at the boundary rather than left for the parent to interpret. `rewarded` IS SERVED WHERE THE PARENT SERVES IT, and answered `no_ad` where it does not. Either way a `shown` grants nothing - see gem.adResult's outcome: the platform grants a rewarded placement's reward itself, into the game's own inventory, against its own record. A game that grants a reward on an outcome has a reward any page that can post on this port can forge."
         }
       },
       "rateLimit": {
@@ -3236,6 +3284,23 @@
         "  unavailable - the shell could not render at all just now. NOT a softer",
         "                no; a game reads it identically to `no_ad`.",
         "",
+        "AFTER A `rewarded` ASK the player pressed a button, so two of those",
+        "readings change. `shown` means an offer sheet was painted and has",
+        "closed, whatever the player chose inside it, and still grants nothing.",
+        "`no_ad` can arrive with the reward already granted - where no ad serves",
+        "and the game's config says to grant without one, for one - so a game",
+        "reads its own inventory, never the outcome, to learn whether a reward",
+        "landed. And where nothing new landed, a neutral 'no reward this time'",
+        "line from the game is right, because the player is waiting on their own",
+        "press; it must never guess a reason.",
+        "",
+        "THAT INVENTORY IS A SECOND CHANNEL, AND THE RULE BELOW DOES NOT CLOSE IT.",
+        "The rule closes the outcome. Whether a reward landed is visible to the",
+        "game by design, so which `no_ad` branches grant one is a disclosure the",
+        "platform decides where it makes the grant. A parent adds nothing to it:",
+        "it never grants, and it answers a rewarded ask exactly as below whatever",
+        "was granted.",
+        "",
         "THREE VALUES, AND THAT IS THE COMPLETE VOCABULARY. `no_ad` absorbs the",
         "feature being switched off, an empty catalogue once the running game is",
         "excluded, a frequency cap that has not expired, and a player whose",

package/schema/capabilities.public.json

@@ -123,6 +123,12 @@
         "gem.frameStats"
       ]
     },
+    "portraitBorders": {
+      "implemented": true,
+      "gates": [
+        "gem.portraitBorders"
+      ]
+    },
     "engagement": {
       "implemented": true,
       "gates": [