@indiegems/gem-web-sdk 7.4.2 → 7.5.0

package/schema/bridge.v1.json

@@ -205,6 +205,33 @@
           "maxLength": 2048,
           "format": "origin",
           "$comment": "The parent's own origin, so the frame can check who is embedding it."
+        },
+        "unbidden": {
+          "kind": "boolean",
+          "optional": true,
+          "$comment": [
+            "True when the parent started this game WITHOUT the player asking — it",
+            "autoplays on an information page, say — rather than because the player",
+            "pressed Play. Absent or false is an ordinary launch.",
+            "",
+            "ON THE HANDSHAKE because it must reach the frame before anything the frame",
+            "counts: the SDK opens its play session the moment the handshake lands, and",
+            "a fact that arrived on any later message would arrive after the session it",
+            "is about. A per-launch FIELD rather than a capability, because a",
+            "capability is a deployment-wide fact about what a peer implements and this",
+            "is a fact about one launch.",
+            "",
+            "Sent to every frame, since the parent cannot know which grammar a frame",
+            "speaks before it answers; a frame that predates the field ignores it, as a",
+            "receiver ignores any unknown field. What a frame that understands it does —",
+            "holds every analytics event that would count a play until the first real",
+            "input inside the frame, and then sends `gem.engaged` — it says by",
+            "advertising `engagement` in `gem.handshake.accept`.",
+            "",
+            "A presentation and measurement fact, NOT AN AUTHORIZATION CONTROL: nothing",
+            "may be granted or withheld on it, and a frame cannot use it to tell a",
+            "player apart from anyone else."
+          ]
         }
       },
       "rateLimit": { "perMinute": 30 }
@@ -2022,6 +2049,40 @@
       "rateLimit": { "perMinute": 5 }
     },
 
+    {
+      "type": "gem.engaged",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "The player has given this frame its first REAL input: a pointer press, a",
+        "key press or a gamepad button press that the browser itself reported",
+        "(`isTrusted`). Focus, hover, wheel and synthetic events do not count. Sent",
+        "once per frame document, and only to a parent that advertised",
+        "`engagement`.",
+        "",
+        "WHY THE FRAME SAYS IT. Input inside a cross-origin frame never reaches the",
+        "parent's own listeners, so a parent can only guess at engagement from focus",
+        "and blur — which a game autoplaying on an information page defeats, since",
+        "nothing about watching it moves focus. The frame is the only party that",
+        "sees the press.",
+        "",
+        "SENT ON EVERY LAUNCH, not only an unbidden one: the first input is a fact",
+        "whatever started the game, and a parent that already knows (the player",
+        "pressed its Play) is free to ignore it. On an unbidden launch it is also",
+        "the moment the SDK releases the analytics it held, so it marks where the",
+        "play session it reports begins.",
+        "",
+        "NO FIELDS, AND IT SHOULD STAY THAT WAY. Which key, where on screen, how",
+        "long after load — none of it is the parent's business, and a field here",
+        "would be one a game could fill with anything. Its occurrence is the whole",
+        "message, like `gem.ready`. A cooperative signal from untrusted code, so",
+        "NOT AN AUTHORIZATION CONTROL: a parent may stop autoplay-related chrome",
+        "and count the launch as engaged on it, and must grant nothing."
+      ],
+      "fields": {},
+      "rateLimit": { "perMinute": 5 }
+    },
+
     {
       "type": "gem.progress",
       "direction": "frameToParent",

package/schema/capabilities.public.json

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