Skip to content

t1k:playablelabs:base:analytics

FieldValue
Modulebase
Version2.29.2
Effortmedium
Tools—

Keywords: applovin analytics events, applovin playable analytics, canonical playable events, playable analytics, playable event tracking, playable-analytics adapter

/t1k:playablelabs:base:analytics
[--engine-host web|none]

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).

IntentPath
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 networkStep 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.

Canonical eventAppLovin nameNotes
LoadStart / LoadCompleteLOADING / LOADEDonly with a loading screen; both or neither
DisplayedDISPLAYEDthe only required event
ChallengeStartedCHALLENGE_STARTEDfirst gameplay input
ChallengeProgress + 25/50/75CHALLENGE_PASS_25/_50/_75any other value is dropped
ChallengeSolved / ChallengeFailedCHALLENGE_SOLVED / CHALLENGE_FAILEDgenuine user outcome only
ChallengeRetryCHALLENGE_RETRYuser retries after a loss
EndCardShownENDCARD_SHOWNthe in-playable end card
CtaClickedCTA_CLICKEDsingle 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”.

GuardWhy
Never define window.ALPlayableAnalytics in game codethe network SDK injects it; only a test stub may
Never ChallengeFailed from a catch / error / timeoutcrashes and load failures are not user failure
Domain/controller code never imports the analytics package or windowemit from the composition root or an injected port (rule playablelabs-decouple-game-code)
Do not call track() from a per-frame updateemit on the crossing, once; dedupe hides it, the cost stays
The debug log shows what the facade emitted, not what the network receivedit prints before the adapter runs; use the stub’s log
Dedupe is once per sessionan in-page replay emits nothing until reset()
Never edit the studio package inside a game repochanges go to its source repo and a republish

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 wire
window.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.

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).