@indiegems/gem-web-sdk 15.0.0 → 15.1.0

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v15.0.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.
+Generated from `@indiegems/gem-web-sdk/sdk` v15.1.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.
 
@@ -3553,6 +3553,72 @@ them, whatever you set here.
 | --- | --- |
 | `props` | `Readonly<Record<string, AnalyticsValue>>` |
 
+<a id="analyticsapi-experiment"></a>
+
+## AnalyticsApi.experiment
+
+```ts
+experiment(key: string, count: number): Promise<number>
+```
+
+Which arm of one of your experiments this player gets — the same answer on
+every call, every refresh and every device. Use it wherever you would have
+picked an arm with `Math.random()`, which deals a player a new arm on each
+visit and makes the test unreadable.
+
+Pass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings
+and get one of them. A string listed twice is twice as likely.
+
+```js
+const tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);
+const layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2
+```
+
+The selection is a hash of the key and the signed-in player's id — FNV-1a
+32-bit over `"<key>:<playerId>"`, then MurmurHash3's 32-bit finalizer, mod
+the arm count; see
+[experimentSelection](#experimentselection), which computes the same answer for an id you
+hold. Hashing the key in is what keeps your experiments independent: the
+players in one experiment's first arm are not the same players in every
+other experiment's first arm.
+
+⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new
+count or list re-deals every player. To start over on purpose, use a new
+key.
+
+⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and
+the SDK does not add it to your events. To analyse an experiment, declare a
+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.
+
+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
+when none arrives — outside the Arcade, the Gem Editor or the dev host.
+There is no random fallback: catch the rejection and play your control arm.
+A guest is selected by their guest id, which is stable for as long as their
+guest account lasts; once they sign in to an account they are that
+account's player, and its selection applies.
+
+In a serverless function it selects for the player who invoked it, with
+no wait, and rejects when a game server invoked it.
+
+Works with analytics turned off: it reads no setting and sends nothing.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | Names the experiment — any non-empty string. |
+| `count` | `number` | How many arms, an integer from 1 to 2048 — or, in the list
+  form, `options`: the arms themselves, 1 to 2048 strings. |
+
+**Returns.** The arm's index, or the chosen string.
+
+**Throws.** TypeError for an empty key or a list holding something other than
+  strings; RangeError for a count or list size outside 1 to 2048. Both
+  reject before waiting for the player.
+
 <a id="analyticsapi-environment"></a>
 
 ## AnalyticsApi.environment
@@ -3680,6 +3746,47 @@ The runtime companion to [PlatformEventName](#platformeventname), for a game tha
 show what it gets for free, or to check a funnel step it authored against
 what the platform actually emits.
 
+<a id="experimentselection"></a>
+
+## experimentSelection
+
+```ts
+function experimentSelection(key: string, playerId: string, count: number): number
+```
+
+Which arm of an experiment a player gets — the same answer for the same key
+and player, every time, anywhere.
+
+In a game, call [AnalyticsApi.experiment](#analyticsapi-experiment) instead: it is this, with
+the signed-in player's id filled in. This form takes the id, for code that
+has one in hand — a dedicated server reproducing what a member's client
+picked, or a test.
+
+Pass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings
+and get one of them. A string listed twice is twice as likely, which is how
+to weight an arm.
+
+The answer is `fmix32(fnv1a32("<key>:<playerId>")) % count`: FNV-1a 32-bit
+over the UTF-8 bytes of the key, a colon and the player id, then
+MurmurHash3's 32-bit finalizer, as an unsigned integer — with a list, the
+index into it. The hash is fixed, so any other language can reproduce a
+selection; docs/analytics.md has it written out.
+
+⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new
+count or list re-deals every player. To start over on purpose, use a new
+key.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | Names the experiment — any non-empty string, and the only thing
+  that makes one experiment's split independent of another's. |
+| `playerId` | `string` | The player to select for — [GemIdentity.playerId](#gemidentity-playerid). |
+| `count` | `number` | How many arms, an integer from 1 to 2048 — or, in the list
+  form, `options`: the arms themselves, 1 to 2048 strings. |
+
+**Throws.** TypeError for an empty key or player id, or a list holding something
+  other than strings; RangeError for a count or list size outside 1 to 2048.
+
 <a id="avatar3dprice"></a>
 
 ## Avatar3dPrice

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

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v15.0.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.
+Generated from `@indiegems/gem-web-sdk/sdk` v15.1.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": "15.0.0"
+    "version": "15.1.0"
   },
   "entries": [
     {
@@ -4393,6 +4393,35 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "AnalyticsApi.experiment",
+          "name": "experiment",
+          "anchor": "analyticsapi-experiment",
+          "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.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "key",
+              "type": "string",
+              "optional": false,
+              "summary": "Names the experiment — any non-empty string."
+            },
+            {
+              "name": "count",
+              "type": "number",
+              "optional": false,
+              "summary": "How many arms, an integer from 1 to 2048 — or, in the list\n  form, `options`: the arms themselves, 1 to 2048 strings."
+            }
+          ],
+          "returns": "The arm's index, or the chosen string.",
+          "throws": "TypeError for an empty key or a list holding something other than\n  strings; RangeError for a count or list size outside 1 to 2048. Both\n  reject before waiting for the player.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "AnalyticsApi.environment",
           "name": "environment",
@@ -4496,6 +4525,41 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "experimentSelection",
+          "name": "experimentSelection",
+          "anchor": "experimentselection",
+          "group": "analytics",
+          "signature": "function experimentSelection(key: string, playerId: string, count: number): number",
+          "documented": true,
+          "summary": "Which arm of an experiment a player gets — the same answer for the same key\nand player, every time, anywhere.\n\nIn a game, call [AnalyticsApi.experiment](api-reference-game.md#analyticsapi-experiment) instead: it is this, with\nthe signed-in player's id filled in. This form takes the id, for code that\nhas one in hand — a dedicated server reproducing what a member's client\npicked, or a test.\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, which is how\nto weight an arm.\n\nThe answer is `fmix32(fnv1a32(\"<key>:<playerId>\")) % count`: FNV-1a 32-bit\nover the UTF-8 bytes of the key, a colon and the player id, then\nMurmurHash3's 32-bit finalizer, as an unsigned integer — with a list, the\nindex into it. The hash is fixed, so any other language can reproduce a\nselection; docs/analytics.md has it written out.\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.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "key",
+              "type": "string",
+              "optional": false,
+              "summary": "Names the experiment — any non-empty string, and the only thing\n  that makes one experiment's split independent of another's."
+            },
+            {
+              "name": "playerId",
+              "type": "string",
+              "optional": false,
+              "summary": "The player to select for — [GemIdentity.playerId](api-reference-game.md#gemidentity-playerid)."
+            },
+            {
+              "name": "count",
+              "type": "number",
+              "optional": false,
+              "summary": "How many arms, an integer from 1 to 2048 — or, in the list\n  form, `options`: the arms themselves, 1 to 2048 strings."
+            }
+          ],
+          "returns": null,
+          "throws": "TypeError for an empty key or player id, or a list holding something\n  other than strings; RangeError for a count or list size outside 1 to 2048.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Avatar3dPrice",
           "name": "Avatar3dPrice",
@@ -28032,6 +28096,35 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "AnalyticsApi.experiment",
+          "name": "experiment",
+          "anchor": "analyticsapi-experiment",
+          "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.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "key",
+              "type": "string",
+              "optional": false,
+              "summary": "Names the experiment — any non-empty string."
+            },
+            {
+              "name": "count",
+              "type": "number",
+              "optional": false,
+              "summary": "How many arms, an integer from 1 to 2048 — or, in the list\n  form, `options`: the arms themselves, 1 to 2048 strings."
+            }
+          ],
+          "returns": "The arm's index, or the chosen string.",
+          "throws": "TypeError for an empty key or a list holding something other than\n  strings; RangeError for a count or list size outside 1 to 2048. Both\n  reject before waiting for the player.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "AnalyticsApi.environment",
           "name": "environment",

package/docs/changelog.md

@@ -16,6 +16,15 @@ 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.
 
+## 15.1.0
+
+Upgrading from 15.0.0. Impact: none.
+
+### New capability
+
+- AnalyticsApi.experiment gives a player a stable experiment arm. Pass an experiment key and either an arm count or a list of options. It returns the same arm for that player on every call, refresh and device: an index from zero up to one less than the count, or one of the strings in the list. Games that picked an arm with a random number landed a player in a different arm on every refresh, so no test could be read. Switching to this call fixes that. Different experiment keys are independent of each other. Nothing is recorded for you. To analyse an experiment, declare a dimension on the events you choose and pass the selection yourself. The call rejects when there is no player.
+- experimentSelection computes the same arm as AnalyticsApi.experiment from an experiment key, a player id you hold, and an arm count or list of options. Use it where the SDK is not running, such as a dedicated game server or an analytics query, to reproduce which arm a player was given.
+
 ## 15.0.0
 
 *Written from the API facts alone; no summary was generated for this release.*

package/docs/getting-started.md

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

package/docs/manifest.json

@@ -13,8 +13,8 @@
     },
     {
       "file": "analytics.md",
-      "sha256": "94baa26268843ba926462633ddec8aaca56aabf79ee6639aaf77df68474debc7",
-      "updated": "2026-10-17T00:33:31Z"
+      "sha256": "afced8f94514818eca6de3e72bdd988b2cee10925086c3bfa47c0a8ec8967454",
+      "updated": "2026-10-23T00:13:14Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -38,8 +38,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "2405f222d6ba0120f9f58dd645a0b8e1659a55faac605935a38d00d50d529e97",
-      "updated": "2026-10-22T16:01:54Z"
+      "sha256": "6b47b52430c201a1eb48a4823b6e3ca59d1e82982428eab0ab7ac3016cc044c1",
+      "updated": "2026-10-23T00:49:37Z"
     },
     {
       "file": "daily-challenges.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "3a6e8a015c5ae067364effd2c0c5432239096d0dc0b5d75ab369194d4f7c8346",
-      "updated": "2026-10-22T16:01:54Z"
+      "sha256": "68ddb1e937d14ba27aadbb2cd19ae59d0cb9048ec2d4435b4d80f87e8ac1eb1a",
+      "updated": "2026-10-23T00:49:37Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -128,8 +128,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "5e07246cbfdb39d211fcee4f4610b9e6ca8ac8439c1a26751cf80ff68f383459",
-      "updated": "2026-10-22T16:01:54Z"
+      "sha256": "c30b720cf1b65dc4e7a2ed25f1dfc86d9c86ba11d69509b45c63183649f3a7aa",
+      "updated": "2026-10-23T00:49:37Z"
     },
     {
       "file": "serverless-functions-js.md",

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/v15.0.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v15.0.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v15.1.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v15.1.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/package.json

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