SDK correlation

How a redeemed Tester Key gets linked to a player's in-game device, same three-method contract in all five official SDKs (TypeScript, Python, Unity, Unreal, Godot).

What it does

When a tester redeems a key via /redeem/<token> they pick a handle (e.g. RedFox42) and receive a Playloop tester token alongside the game key. The tester pastes that token into the game once; the SDK calls Playloop's claim endpoint; from then on every telemetry event from this device auto-tags with their handle server-side. The studio sees RedFox42 in dashboards instead of an opaque deviceId.

The three methods

All three resolve gameId from per-call > SDK config > error. Most studios set the config gameId once at construction time.

Wire protocol

POST   /api/telemetry/claim          { claimToken, gameId, deviceId }
                                     → 200  { ok: true, alreadyLinked, handle, claimedAt }
                                     → 404  { ok: false, reason: 'unknown' }  (uniform, see Anti-enumeration)

GET    /api/telemetry/tester         ?gameId=&deviceId=
                                     → 200  { linked: true, handle, claimedAt } | { linked: false }

DELETE /api/telemetry/claim          { claimToken, gameId, deviceId }
                                     → 200  { ok: true, unlinked: boolean }
                                     → 404  { ok: false, reason: 'unknown' }  (uniform)

Public surfaces, no auth needed; the claim token IS the credential, and the deviceId is the SDK's local identity. All three are rate-limited per IP.

Anti-enumeration

POST and DELETE both collapse every rejection path to the uniform 404 { ok: false, reason: 'unknown' } shape. Wrong-token, wrong-game, wrong-device, already-bound, all look identical on the wire. Playloop's own audit log distinguishes them server-side (cross-game claim, device conflict, unbind rejected, etc.) for studios debugging support cases. The collapse closes a cross-studio inventory-enumeration vector that granular response codes opened, and the DELETE handler additionally requires the original claimToken so a leaked (gameId, deviceId)from an exported CSV / audit row can't be used to grief attribution.

Cross-game isolation

The binding key is (gameId, deviceId). A claim token issued for game A cannot link a device for game B, the server returns the uniform unknown 404. Same applies to getCurrentTester and unlinkTester: each query is scoped to one game. A device can be linked to different testers across different games.

Idempotency

• linkTester from the SAME device with the SAME token → returns alreadyLinked: true. Cheap; safe to call on every game launch.
• linkTester from a DIFFERENT device → uniform 404 unknown. Tester must unlink the original device first, OR get a fresh invite.
• getCurrentTester → read-only, no state change. Call on every menu render if you want.
• unlinkTester when nothing is linked → returns unlinked: false (only after the claim-token authorization passes).

Where to surface the input in your game

Three common placements. Pick the one that matches your audience. Whatever you pick, the field is a plain text input that accepts a 32-char base32 token plus the pl_tt_ prefix, nothing special.

Pattern A, Settings menu (recommended default)

Add an item under Settings → Beta tester ID (or Playtest token, Tester linking, whatever matches your naming). Shows the bound handle when linked, prompts for a token when not. Players can ignore it forever and the game plays exactly the same.

• Pros: opt-in by design. Non-tester players never see a "what is this?" prompt.
• Cons: testers may forget the menu exists. Pair with a sentence in your redemption email: "After you redeem on Steam, open Settings → Beta tester ID and paste your tester token."
• Best for: games shipped to a mix of paying customers + private testers (Steam Next Fest demos, paid Early Access with a closed beta channel).

Pattern B, First-launch dialog

On first boot only (track a flag in your player prefs), show a small dismissible card: “Got a Playloop tester token? Paste it here so the studio can see your feedback. Skip if you weren't sent one.” Two buttons: Link + Skip. Never shows again unless the player navigates to Settings.

• Pros: highest link-rate; testers see the prompt at the exact moment they have the token from your email/redemption page open.
• Cons: non-tester players see a moment of "what?" on their first launch. Keep the copy short and the Skip button obvious.
• Best for: closed alphas / playtest-only builds where the majority of installs ARE testers.

Pattern C, Pause menu link

Add a small “Link Playloop tester token” option to the pause menu (or main menu). Always there, never intrusive, easy to reach mid-session if a tester realises they forgot to link before starting.

• Pros: low-effort retrofit when you don't have a settings menu yet.
• Cons: always visible to non-testers; can feel cluttered in a polished pause menu.
• Best for: game-jam-style or early-prototype builds where you want the cheapest path to ship it.

What to put in the copy next to the input

• "Paste your Playloop tester token to link your sessions to the studio."
• "Optional, your save / progress / Steam key all work without this."
• "Find your token at the URL you used to claim your key."

After a successful link, replace the input with a confirmation: “Linked as RedFox42 · switch”. The switch link calls unlinkTester and re-renders the input. See Full UX (15 lines) below for the code shape.

Minimum integration (5 lines)

The bar is intentionally low so studios actually ship this. A single text input in your main menu + one call:

TypeScript

const token = await prompt('Enter your Playloop tester token (optional):')
if (token) await client.linkTester({ claimToken: token })

Python

token = input("Enter your Playloop tester token (optional): ").strip()
if token:
    await client.link_tester(claim_token=token)

Unity (C#)

var token = mainMenuInput.text;
if (!string.IsNullOrEmpty(token))
{
    await client.LinkTesterAsync(token);
}

Godot (GDScript)

var token: String = $TesterTokenInput.text
if token != "":
    await playloop.link_tester({ "claim_token": token })

Full UX (15 lines)

Show who they're playing as + offer a “Switch tester” affordance:

TypeScript

const tester = await client.getCurrentTester()
if (tester.linked) {
  showLabel(`Playing as ${tester.handle}`)
  // Persist the claim token locally at linkTester time so you can
  // pass it back on unlink (the server requires it — audit L-6).
  onSwitchTester(async () => {
    await client.unlinkTester({ claimToken: storedClaimToken })
    reloadMenu()
  })
} else {
  const token = await prompt('Enter your Playloop tester token (optional):')
  if (token) await client.linkTester({ claimToken: token })
}

The other three SDKs mirror this shape, see each SDK's README “Linking a tester” section for the language-specific code.

Setting gameId once

All three methods resolve gameId from per-call > config. Set it on the SDK constructor so per-call args stay optional:

TypeScript

const client = new Playloop({
  apiKey: process.env.PLAYLOOP_INGEST_KEY!,
  gameId: 'game_xyz',   // ← per-call linkTester etc. resolve from here
})

Python

client = Playloop(
    api_key=os.environ["PLAYLOOP_INGEST_KEY"],
    game_id="game_xyz",
)

Unity (C#)

var client = new PlayloopClient(new PlayloopOptions
{
    ApiKey = "pl_ik_...",
    GameId = "game_xyz",
});

Godot (GDScript)

playloop.configure({
    "api_key": "pl_ik_...",
    "game_id": "game_xyz",
})

You can still pass gameId per-call to override (multi-game studios where one client talks to several titles).

Errors to handle

Per the Anti-enumeration section above, every rejection collapses to the uniform 404 { ok: false, reason: 'unknown' } on the wire. Unknown token, wrong game, different-device conflict, and unbind-of-nothing all look identical. The SDK surfaces the same friendly message in every reject case. (The server-side audit log distinguishes them for studios debugging support cases.)

The link is non-critical: a failed linkTesterdoes NOT prevent the player from playing. Telemetry will still flow; it just won't carry the handle until the next successful link.

How attribution actually fires

When the SDK calls linkTester, Playloop binds the tester's handle to the device. On every subsequent POST /api/telemetry from this device, the session-create path looks up that binding and stamps the session with the handle the tester picked at redemption.

Read sites (per-game user list, build-summary, analytics) already group by tester handle, no extra wiring needed. The studio sees RedFox42 appear in dashboards within seconds of the first session after linkTester.

Geo-stamping piggybacks: the same path records the country observed at this session's ingest. A future rollup uses those to compute the per-key “likely shared” flag.

What NOT to do

• Don't call linkTester on every launch with the same token unconditionally, it's idempotent so it'll work, but you're burning a network round-trip. Call getCurrentTester first; only call linkTester if linked === false AND the player just entered a token.
• Don't store the claim token in logs / save files / cloud sync. It's a one-shot credential. Once linked, the server owns the binding; the SDK doesn't need the token again.
• Don't auto-prompt for the token on every game start, only on first launch OR when the player opens a “Link my Playloop tester key” menu item. Tester tokens are optional; you don't want to nag every player every time.
• Don't use one tester's deviceId across multiple human testers, the binding becomes nonsense (“RedFox42” got attributed to a session played by their sibling). One install = one device = one tester.