t1k:playablelabs:base:analytics
| Field | Value |
|---|---|
| Module | base |
| Version | 2.29.2 |
| Effort | medium |
| Tools | — |
Keywords: applovin analytics events, applovin playable analytics, canonical playable events, playable analytics, playable event tracking, playable-analytics adapter
How to invoke
Section titled “How to invoke”/t1k:playablelabs:base:analytics[--engine-host web|none]Playable Analytics (web / none hosts)
Section titled “Playable Analytics (web / none hosts)”Event tracking for a packed playable: the game calls one canonical track(event) per moment, a per-network adapter
maps it to that network’s own event name. One build runs on many networks.
Provenance: engine-neutral half of t1k-cocos-playable-analytics (theonekit-cocos, module playable, v4.8.10 read), rewritten for the web template’s game flow. Engine-neutral facts (events, adapter contract, dedupe,
buffer) are kept; the editor/scene attach, component lifecycle and signal-bus parts are dropped.
Does NOT cover: the packer-side CTA / MRAID (game_end() then download()) -> t1k-playablelabs-base-engine-hosts
and t1k-playablelabs-base-networks; the packed-artefact boot check -> t1k-playablelabs-base-smoke; dashboard
parameters -> t1k-playablelabs-base-params. Link to them, never restate.
Precondition: the package must be engine-free before web use
Section titled “Precondition: the package must be engine-free before web use”The studio package @playablelabs/playable-analytics (v0.1.3 read) has exactly ONE engine import,
core/PlayableAnalytics.ts:1 (import { log, warn } from 'cc', used only for the debug log and the one-shot
“track() before init()” warning). A web/none game cannot resolve that module. Do not import the package into a web
game until that line is replaced by an injected or console logger (the change belongs in the package’s own repo and
a republish; never patch a vendored copy). Until then the contract below is the spec to code against; record the verdict
with t1k-playablelabs-base-cpm-sweep (reuse-verdict: unverified if the registry was not reachable). Distribution on
web is a versioned dependency in the game’s package.json, not a sync list (cpm-sweep/references/cpm-facts.md).
Decision tree
Section titled “Decision tree”| Intent | Path |
|---|---|
| should this playable track at all? | Step 0 |
where does a track() call go in the web template? | Step 1 -> references/event-placement.md |
| add a network (MRAID / IronSource / Mintegral / Google) | references/add-network-adapter.md |
| prove the stream without a real network | Step 2 -> references/verification.md |
Step 0: should this playable emit analytics?
Section titled “Step 0: should this playable emit analytics?”AppLovin policy. Set the master switch off and stop when any holds: fewer than 3 interactions to complete;
redirect < 5 s after the first interaction; no win/lose challenge (pure demo). Shape unclear -> ask before wiring.
A no-challenge playable that tracks ChallengeStarted breaks the pairing rule below and network policy.
The contract (engine-neutral)
Section titled “The contract (engine-neutral)”| Canonical event | AppLovin name | Notes |
|---|---|---|
LoadStart / LoadComplete | LOADING / LOADED | only with a loading screen; both or neither |
Displayed | DISPLAYED | the only required event |
ChallengeStarted | CHALLENGE_STARTED | first gameplay input |
ChallengeProgress + 25/50/75 | CHALLENGE_PASS_25/_50/_75 | any other value is dropped |
ChallengeSolved / ChallengeFailed | CHALLENGE_SOLVED / CHALLENGE_FAILED | genuine user outcome only |
ChallengeRetry | CHALLENGE_RETRY | user retries after a loss |
EndCardShown | ENDCARD_SHOWN | the in-playable end card |
CtaClicked | CTA_CLICKED | single redirect chokepoint |
Custom | (dropped on AppLovin) | only for a network that supports custom events |
Facade: track(event, value?, custom?), master switch enabled, once-per-session dedupe, a 32-event buffer replayed in
order when a real adapter attaches, reset() for a replay, forceAdapter ('noop' / 'applovin') for tests.
Adapter: name, isPresent() rechecked on EVERY call (the SDK may inject late), track() never throws and drops an
unmapped event silently, optional reset() for per-session state. AppLovin: window.ALPlayableAnalytics.trackEvent(name)
behind a typeof guard; an orphan LOADED (no prior LOADING) is auto-dropped. No network present -> NoOp adapter.
Step 1: placement (one chokepoint per event)
Section titled “Step 1: placement (one chokepoint per event)”One moment, one call site; two sites double-emit on a path that hits both. In the web template the chokepoints are the
composition root (main.ts boot()), the controller’s outcome latch and platform/cta.ts. Per-event table and snippets:
references/event-placement.md. Pairing rules (a violation is a broken stream): LOADING => LOADED;
CHALLENGE_STARTED => at least one SOLVED / FAILED; no loading screen => neither LOADING nor LOADED.
Displayed must never wait on a readiness signal without an escape hatch (first interaction and/or a timer): a poll
with no timeout turns “wait for ready” into “never report”.
Guards
Section titled “Guards”| Guard | Why |
|---|---|
Never define window.ALPlayableAnalytics in game code | the network SDK injects it; only a test stub may |
Never ChallengeFailed from a catch / error / timeout | crashes and load failures are not user failure |
Domain/controller code never imports the analytics package or window | emit from the composition root or an injected port (rule playablelabs-decouple-game-code) |
Do not call track() from a per-frame update | emit on the crossing, once; dedupe hides it, the cost stays |
| The debug log shows what the facade emitted, not what the network received | it prints before the adapter runs; use the stub’s log |
| Dedupe is once per session | an in-page replay emits nothing until reset() |
| Never edit the studio package inside a game repo | changes go to its source repo and a republish |
Step 2: verify headlessly
Section titled “Step 2: verify headlessly”No real network is needed: stub ALPlayableAnalytics before page scripts, drive the game through its QA seam, read
the log. Full table with expected output per row: references/verification.md.
// page.addInitScript(...) (or a <head> script in a dev build): records the wirewindow.ALPlayableAnalytics = { _log: [], trackEvent(n) { this._log.push(n); } };Expected on a win path with a loading screen: LOADING, LOADED, DISPLAYED, CHALLENGE_STARTED, CHALLENGE_SOLVED, ENDCARD_SHOWN (order is the game’s; what is asserted is the pairing and once-only rules). Also run
t1k-playablelabs-base-smoke with the SAME --engine-host: with no stub present the NoOp path must not raise a page
error (a page error fails the smoke row). Smoke boots only; it does not reach win/lose, so the stub run is the proof.
Related
Section titled “Related”t1k-playablelabs-base-engine-hosts (CTA order, boot globals) · t1k-playablelabs-base-networks (per-network CTA) ·
t1k-playablelabs-base-smoke · t1k-playablelabs-base-params · t1k-playablelabs-base-cpm-sweep ·
t1k-gamedev-playable-qa-flows / t1k-gamedev-playable-preview-verify (drive win/lose headlessly) ·
this skill is event EMISSION; detecting analytics hooks in a reference build is the ref module’s extraction (detection only).