@tesana/sdk
v1.5.0
Published
Tesana play-time SDK — players, cloud saves, leaderboards, achievements and the in-game coin shop for a web game.
Maintainers
Readme
@tesana/sdk
Tesana's play-time SDK. It gives a web game a player identity, cloud saves that follow that player to another device, leaderboards, achievements, and the in-game coin shop — without the game talking to any of those services directly.
The SDK is what the global window.Tesana is. In a game published on Tesana the
platform injects it and hands over the player and the game's identity; the game
just calls it.
Install
npm install @tesana/sdkUse
An exported game boots from the global, because Tesana's own guidance forbids importing a package into game code:
<script src="https://unpkg.com/@tesana/sdk/dist/tesana.iife.js"></script>
<script type="module">
const tesana = await window.__TESANA_READY__;
const save = await tesana.db.get("save");
</script>Bundled or module code can import it instead, which is the same client:
import Tesana from "@tesana/sdk";
const tesana = await Tesana.init();
await tesana.db.set("save", { level: 7 });init() accepts { gameId, endpoint, playerToken }. With none of them it reads
window.__TESANA__, then asks the host page over postMessage, and finally
falls back to a guest identity — so a game still runs with no host, no network
and nobody signed in. Never gate the game itself behind a service call
succeeding.
Surfaces
| | |
|---|---|
| tesana.db | Cloud saves — get / set / list / collection |
| tesana.scores | Leaderboards — submit / top / me / best |
| tesana.achievements | Badges — list / unlocked / unlock / progress |
| tesana.shop | In-game shop — catalog / items / buy / entitlements / inventory |
| tesana.economy | Coins — balance / packs / topUp / signIn |
| tesana.multiplayer | Open lobbies — list / create / join / quickJoin / send / on |
| tesana.player | Identity — me / isGuest / login() (asks the host to sign in, like economy.signIn) |
| tesana.vanity | The game's own address on tesana.ai |
| tesana.ads | Ads, when the host allows them |
| tesana.gameplay | Progression events — levelStart / levelComplete / levelFail / death / checkpoint / score |
| tesana.track | Any other gameplay event, by name |
| tesana.feedback | Player reports to the creator — open (host form) / submit; crashes are filed automatically |
| tesana.config | Values the creator tunes without a rebuild — get(key, default) / getAll / ready |
| tesana.share | Invite links — share({ roomCode, levelId, text }) / share.params() |
| tesana.build | This build's id (its hash), from the host or the page's <meta name="tesana-build">; "" when neither says |
| tesana.release | The release number when this build is the release players have, else null |
| tesana.locale | The player's language as a BCP 47 tag, e.g. "ko-KR" (since 1.4.0; see Languages) |
| tesana.l10n | The platform's translation of declared strings — t / locale (the site's language) / languages / onChange |
| Tesana.reservedArea() | The top-right box the Tesana player keeps for its button on a phone (since 1.5.0; see The player's corner) |
The player's corner (since 1.5.0)
On a phone, the Tesana player draws one button over the game's top-right
corner. Tesana.reservedArea() (also tesana.reservedArea()) says where, so a
game keeps its pause button, minimap and score out of it: { top, right,
width, height } in CSS px of the game's viewport, from its top-right corner.
It is synchronous, needs no init(), and returns a fresh object each call:
read it again on resize and on window's tesana-reservedareachange.
| Host | Box |
|---|---|
| Web player, or no host | { top: 12, right: 12, width: 36, height: 36 }, with top/right raised to the page's env(safe-area-inset-*) when that is larger (read on every call) |
| Tesana app (a TesanaApp/<version> user agent) | { top: 8, right: 8, width: 36, height: 36 } |
| A host that sends reservedArea | exactly that box ({ top: 0, right: 0, width: 0, height: 0 }: nothing reserved) |
A host names its box with reservedArea on the bootstrap, and moves it later
(a rotation, a new safe-area inset) by posting
{ type: "tesana-reserved-area", reservedArea: { top, right, width, height } }
into the frame. The newest box wins, and each one fires
tesana-reservedareachange on window. A box with a missing, negative or
non-number side is ignored.
function placeHud() {
const r = window.Tesana?.reservedArea?.() ?? { top: 12, right: 12, width: 36, height: 36 };
pauseButton.style.top = `${r.top}px`;
pauseButton.style.right = `${r.right + r.width + 8}px`; // left of the Tesana button
}
placeHud();
addEventListener("resize", placeHud);
addEventListener("tesana-reservedareachange", placeHud);The ?. form keeps a game working on an SDK older than 1.5.0.
Languages (since 1.4.0)
A game that ships its own translations picks one at start from
tesana.locale: the site's language when the player picked it, English
included (the host says so with localeChosen: true on the bootstrap and on
each tesana-locale change; a host that does not say counts only a
non-English language as picked), otherwise the browser's first language, as a
canonical BCP 47 tag (ko-KR, fr, zh-Hant-TW). The
site sends en to every visitor who has not picked a language, so
tesana.l10n.locale() (the site's language, which the platform translates
into) says en for most Korean or French players; tesana.locale does not.
Match its base tag against the languages the game ships and fall back to
English. A change while playing fires tesana.l10n.onChange.
const shipped = ["en", "ko", "fr", "ja"];
const base = tesana.locale.toLowerCase().split("-")[0];
const lang = shipped.includes(base) ? base : "en";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.
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.levelFail("forest", "out_of_time");
tesana.gameplay.score({ value: 4200 });
tesana.track("powerup_picked", { kind: "triple_shot" });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.levelFail(props?: GameplayProps | string | number, reason?: string): boolean; // since 1.3.0
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
truewhen the event was handed on andfalsewhen 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 globalTesana, 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, elsepostMessage({ type: "tesana-gameplay-event", event })to the parent.eventis the shapePOST /api/games/<id>/play/events/stores:type(level_start,level_complete,death,checkpoint,scoreorcustom),name,level_id,level_index,x,y,z,value,payload,ts. tracknames. A name that is one of the types above files the event as that type; any other name is acustomevent 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.
First-party events (since 1.3.0)
The level calls also go to Tesana's event collector (POST /api/e on the API,
TES-2197), and the SDK adds two events by itself: a play heartbeat for every
15 s the game is in front (active after a key, pointer, touch or gamepad
input in the last 30 s, else open) and a quit when the page closes, naming
the level the player was in. The heartbeat clock runs only while the page is
visible and resumes where it stopped, so a return to the tab sends nothing at
once (TES-2641). Types and properties are the backend registry's
(one_tap/events/registry.py):
| Type | When | props |
|---|---|---|
| game.level.started@1 | levelStart | level, level_index |
| game.level.ended@1 | levelComplete, levelFail | level, outcome (completed or failed), duration_ms, reason |
| game.session.quit@1 | pagehide | level, in_level, seconds |
| play.session.heartbeat@1 | each 15 s in front | state (open or active), level |
- Where. Only from Tesana's play hosts:
play.tesana.aisends to production's API,play-staging.tesana.aito staging's. A host can name the collector instead (eventsEndpointin the bootstrap, for a desktop build's prelude; none does yet, so desktop builds send nothing). Any other page, localhost and preview sandboxes included, sends nothing, and so does a QA rig (__TESANA_QA_RIG__), an automated browser (navigator.webdriver), a test's DOM (jsdom) or a host that saysevents: false. - Only a real play page (TES-2640). Studio previews run on the same play
host, so nothing is sent until the page is known not to be one: the host
says
studio: false, names its collector, or posts a play token without thestudioclaim the play service stamps on a Studio test session. Until then events wait in the queue;studio: trueor a Studio token drops them. - The game. Named by the bootstrap's
gameId: its public id goes asplay_game_id(the collector stores the game's id), a site id asgame_id. No id, nothing is sent. - Nothing personal (TES-2639). No device id: the SDK's device id can be
traded for that guest's play token, so it never goes to analytics. The
browser is named by its own random
anonymous_id. - The account, named by the server (since 1.3.1, TES-2722). The SDK never
sends a user id. A signed-in player's batch carries the site's play session
token (the bootstrap's
token, the one the shop calls send) astokenin the body, since a beacon can't carry an Authorization header. The collector checks it (signature, expiry, and that it is this game's) and stores the events with the player's account; a guest's events, or a forged, expired or other game's token, stay anonymous. A play service token (a JWT, all a guest holds) never goes. The token goes only to Tesana's own collectors, never to one a host or the game names (TES-2729), and a host answer without it (a sign-out) takes it away at once, even one the session refuses to adopt (TES-2730). - Delivery. Batched every 30 s (at once at 50 events), and flushed by
navigator.sendBeaconwhen the page is hidden or closed, as JSON labelledtext/plain; a keepalivefetchwhen there is no beacon. Every event has its own UUID, so a batch that arrives twice is stored once. Offline, a batch is dropped. Never throws, never blocks.
Offline behaviour
Every call resolves rather than throwing when there is no host, no endpoint or
no network. Saves read as empty, the shop reports no_host, and the game plays.
config.get answers the last session's value or the game's default, and
feedback.open() and share() resolve { ok: false, reason }. Writes that
report something (scores.submit, feedback.submit) reject, so the game can say
it did not send.
Real money is never the game's business — topUp() asks the host to run
checkout, and the price shown is read from the service.
Building this package
The published artifact is generated, not hand-written:
npm run build:sdk # writes dist/tesana.iife.js and dist/tesana.esm.js
npm run version:sdk -- 1.2.0 # bumps VERSION and package.json togetherbuild.js refuses to build if VERSION in src/tesana.js and version in
package.json disagree — the engine derives each game's pinned /sdk/v<major>/
URL from the first and npm resolves the second, so a mismatch would publish a
package whose declared version is not the SDK inside it.
License
Proprietary. Copyright Tesana. All rights reserved. Not for redistribution.
