Versions and changelog
Browser, PHP and Python SDK packages are version 0.3.0. Repository manifests define their versions; npm/Composer/PyPI and CMS marketplace publication are separate actions. /v1 is the HTTP contract version, not the SDK version.
Loading and caching
GET /v1/game-assets/sdk/v0-3-0/release.json lists the hashed sdk and loader filenames. Load them below the same directory. A published version and its files must remain immutable; change the SDK version for the next release and retain older published files while clients depend on them. The current build only ships its own version; retention across future deployments needs release management. Do not silently reuse 0.3.0 for changed bytes.
The stable /v1/widget.js alias uses no-cache, max-age=0, must-revalidate and a content SHA-256 ETag. If-None-Match returns 304 with no body when unchanged. This alias intentionally picks up fixes; a pinned loader requires explicit upgrading. Hashed assets support gzip/Brotli and immutable caching.
Compatibility
| Old interface | Current interface and migration |
|---|---|
| PlayFlow constructor / PHP namespace / playflow Python module | Retained technical names; JS also exposes RetentionPlay |
| JS issueSessionToken / browser apiKey | Safe error; issue on your backend using SessionTokens::issue or issue_session_token |
| Locally signed session JWT | Unsupported; request the platform-issued token with session:issue key |
| X-PlayFlow-Server-Key | Accepted, as is X-RetentionPlay-Server-Key; prefer Authorization Bearer |
| X-PlayFlow-Signature | Accepted alongside X-RetentionPlay-Signature; same signature value |
| Progress session_token query | Accepted legacy fallback; migrate to Authorization to keep tokens out of URLs |
| Public preview attribute | CMS refuses without loader; owner preview in authenticated admin. Change mode explicitly to enable play |
| WEBHOOK_SIGNING_SECRET | Deprecated platform fallback when WEBHOOK_SIGNING_MASTER_KEY is absent; receiver uses its revealed project secret |
Provided identified tokens need your backend's renewal and SDK remount. Preserve the same external_user_id to continue server progress. Anonymous sessions use the loader's bootstrap/renewal flow. Destroyed SDK objects cannot be mounted again.
The test matrix uses actual frozen SDK/loader bytes from commit 9d1da44 against new SDK/loader. It proves mount, handshake, a real command and teardown for all four pairs, in Chromium and WebKit. Old query-based progress is not a privacy guarantee; only the new SDK uses headers. CMS checks execute Liquid and the actual WordPress plugin with a minimal callback fixture; store installation, third-party WordPress filters and external CI are separate checks.
0.3.0 — 2026-10-09
- Header-only JS progress, HTTP error propagation and cancellation on destroy.
- Explicit migration errors for browser token issuance and server keys.
- Independent Shopify inserts, escaped attributes and WordPress URL/target sanitization.
- Versioned minified assets, ETag loader revalidation and compatibility fixtures.
- PHP/Python environment-based issuance and webhook receiver examples.
- OpenAPI wheel routes, authentication and request-limit documentation aligned with the server.