JS SDK

A thin browser wrapper over the RetentionPlay loader, in sdk/js/playflow.js. It mounts the widget programmatically, can read progress and releases an instance on teardown.

Browser SDK does not issue tokens

The JS SDK runs in the browser, so it must never hold API keys or secrets. For identified play, have your backend call POST /v1/server/session-token with a session:issue API key and pass the returned session_token in.

Usage

SDK 0.3.0 is served as a versioned, hashed asset; resolve its filename from /v1/game-assets/sdk/v0-3-0/release.json (see versioning). For a self-hosted integration, copy sdk/js/playflow.js into your own static assets and self-host it (or skip it entirely and use the raw embed snippet directly — mount() below is just a thin convenience wrapper over the exact same loader script tag).

<div id="playflow-widget"></div>
<script src="/assets/playflow.js"></script>
<script>
  var pf = new PlayFlow({
    apiBase: 'https://api.example.com',
    projectId: 'proj_demo',
    sessionToken: 'SESSION_TOKEN', // from your backend; omit for anonymous free-play
    target: '#playflow-widget',
  });

  pf.mount();

  pf.fetchProgress().then(function (state) {
    console.log('streak', state.progress.streak_current);
  });
</script>

API

Member	Description
new PlayFlow(options)	apiBase, projectId, sessionToken?, target?
.mount()	Injects the loader script with the right data-* attributes; repeated calls on the same instance do not mount twice
.fetchProgress()	Reads progress with Bearer authorization; rejects HTTP errors with API error code and error.status
.issueSessionToken()	Throws a migration message pointing to server PHP/Python helpers; never sends a key
.destroy()	Idempotently removes this instance's loader and widget, including before the loader finishes loading; returns the SDK instance

mount() is equivalent to the raw embed snippet: use whichever fits your stack.

Call pf.destroy() when leaving a route or removing its component. It preserves the mount target and sibling DOM, aborts SDK progress and loader requests and removes its listeners. Late loader execution or replies cannot remount a destroyed instance. mount() after destruction has no effect; create a new PlayFlow instance to mount again. RetentionPlay is also available as the constructor's public-name alias.

RetentionPlay.VERSION is 0.3.0. Passing apiKey to the constructor throws before mounting or making a request. Provided identified tokens are not renewed automatically: obtain a replacement through your backend, destroy the instance and mount a new instance with the token for the same player. Server run progress survives remount. Anonymous sessions retain the loader's anonymous renewal flow.