Getting started

Triggair is a game backend for browser games. You integrate it with one import and one publishable key; player-scoped calls authenticate themselves, and every error tells an agent how to fix it.

Keys

Every game has two key kinds. The publishable key (tg_pk_…) is safe in client code: it identifies the game and is origin-checked (CORS). The secret key (tg_sk_…) is server-only and must never ship in a client. Issue and rotate keys in the dashboard (Setup → Keys) or via the API. Only the SHA-256 hash is stored; the full key is shown once.

import { createClient } from '@triggair/sdk';
const tg = createClient({ key: 'tg_pk_your_key' });

Anonymous-first identity

There are no accounts or login screens by default. On first use the SDK mints an anonymous player token from a stable device id and silently refreshes it; every player-scoped call attaches it. For cross-device rescue, mint a recovery code the player saves once and redeem it on the new device.

const { playerId } = await tg.login();
const { code } = await tg.mintRecoveryCode(); // show once
await tg.recover(code);                         // same player, new device

display_name vs handle

A player has two name fields, and they do different jobs. display_name is the name shown on leaderboards and profiles (it is the display_name field of a BoardEntry). handle is a separate, unique, lowercased @mention-style id for lookups (players.lookup(handle)), not the board name. So calling players.updateProfile({ handle }) on its own leaves display_name null and boards show no name: set display_name for the visible name. A taken handle throws conflict; a handle is lowercased and must be 3 to 20 chars of a-z, 0-9, or _.

await tg.players.updateProfile({ display_name: 'Ada Lovelace', handle: 'ada' });
// leaderboards now show 'Ada Lovelace'; others can find the player via lookup('ada')

CORS: the 'works locally, 403s deployed' trap

Browser calls are origin-checked. If a call only fails once deployed, add your deployed origin to the game's allowed_origins (Setup → Keys/CORS). An empty allowlist is open to any origin, so set it before you ship.

Close the loop

After wiring the SDK, run the self-test: the MCP tool triggair_verify_integration or the dashboard's verify runner. It live-probes player → save → leaderboard → CORS and reports pass/fail per service with fixes.