@tesana/sdk 1.0.3 → 1.1.0

package/README.md

@@ -55,11 +55,66 @@ succeeding.
 | `tesana.player` | Identity — `login({ tesanaUserId })` |
 | `tesana.vanity` | The game's own address on tesana.ai |
 | `tesana.ads` | Ads, when the host allows them |
+| `tesana.gameplay` | Progression events — `levelStart` / `levelComplete` / `death` / `checkpoint` / `score` |
+| `tesana.track` | Any other gameplay event, by name |
 
 Leaderboards and achievements are client-reported, so they are a ranking to show
 off rather than a prize table; nothing here mints coins or grants entitlements.
 A counted achievement is decided by the server, not the game.
 
+### Gameplay analytics
+
+`tesana.track` and `tesana.gameplay` report what happened in the game so its
+creator can see where players get stuck and where they quit. They go to the
+Tesana page above the game, which files them against the play session; there
+is no key and no third-party provider.
+
+```js
+tesana.gameplay.levelStart({ levelId: "forest", levelIndex: 1 });
+tesana.gameplay.death({ levelId: "forest", x: player.x, y: player.y });
+tesana.gameplay.checkpoint({ levelId: "forest", name: "bridge" });
+tesana.gameplay.levelComplete({ levelId: "forest" });
+tesana.gameplay.score({ value: 4200 });
+tesana.track("powerup_picked", { kind: "triple_shot" });
+```
+
+```ts
+type GameplayProps = {
+  levelId?: string | number;   // the join key: the same value in every call for one level
+  levelIndex?: number;         // 0-based position, when levels are ordered
+  x?: number; y?: number; z?: number;  // where it happened (deaths draw the heatmap)
+  value?: number;              // a score, a count
+  name?: string;               // a death's cause, a checkpoint's name
+  [context: string]: string | number | boolean | null | undefined;
+};
+
+track(name: string, props?: GameplayProps): boolean;
+gameplay.levelStart(props?: GameplayProps | string | number): boolean;     // bare value = levelId
+gameplay.levelComplete(props?: GameplayProps | string | number): boolean;
+gameplay.death(props?: GameplayProps | string | number): boolean;
+gameplay.checkpoint(props?: GameplayProps | string | number): boolean;
+gameplay.score(props?: GameplayProps | number): boolean;                   // bare value = value
+```
+
+- **Never throws, never async.** Each call answers `true` when the event was
+  handed on and `false` when it was dropped (a bad name, too many events, or no
+  Tesana page and no runtime shell to hand it to). Call it inline, unguarded.
+- **No `init()` needed.** The same functions are on the global `Tesana`, so a
+  game can report its first level before `__TESANA_READY__` resolves.
+- **Delivery.** The runtime shell's `window.__TESANA_EVENT__` when the page has
+  it, else `postMessage({ type: "tesana-gameplay-event", event })` to the parent.
+  `event` is the shape `POST /api/games/<id>/play/events/` stores: `type`
+  (`level_start`, `level_complete`, `death`, `checkpoint`, `score` or `custom`),
+  `name`, `level_id`, `level_index`, `x`, `y`, `z`, `value`, `payload`, `ts`.
+- **`track` names.** A name that is one of the types above files the event as
+  that type; any other name is a `custom` event with that name.
+- **Caps.** Names are cut to 64 characters. Up to 20 context keys are kept
+  (keys cut to 40 characters, strings to 64); objects, arrays, functions and
+  non-finite numbers are dropped, and keys stop being added before the payload
+  passes the endpoint's 2,000-character limit.
+- **Rate.** At most 10 events in any one second and 1,000 per page load. Report
+  discrete moments — a level, a death, a run's end — never every frame.
+
 ### Offline behaviour
 
 Every call resolves rather than throwing when there is no host, no endpoint or