t1k:cocos:playable:analytics
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | medium |
| Tools | — |
Keywords: ALPlayableAnalytics, analytics, applovin analytics, event tracking, playable events, PlayableAnalytics, PlayableEvent, track event
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:analyticsCocos Playable Analytics
Section titled “Cocos Playable Analytics”Event tracking for playable ads through @playablelabs/playable-analytics. Your game calls one
canonical PlayableAnalytics.track(event) per event; each ad network’s adapter maps it to that
network’s own name. One build runs on many networks.
<cocos-project> = the Cocos project dir (the one holding assets/; CocosPlayableAdsTemplate/ in the template, Cocos<Name>PLA/ in a game).
API detail lives in the package README — <cocos-project>/assets/packages/@playablelabs/playable-analytics/README.md.
Read it for signatures, the canonical→AppLovin map, and config keys. This skill is the decision
layer: whether to track, where to place a call, which guards bind, and how to prove the stream.
Does NOT cover: SDK selection / adapter plumbing / CTA routing (t1k-cocos-playable-sdk-core), or
game-flow states and views (t1k-cocos-playable-gameflow).
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “should this playable track at all?” | Step 0 |
| “is the bootstrap actually wired?” | Step 1 |
“where do I put a track() call?” | Step 2 → references/event-placement.md |
| “add IronSource / Mintegral / Google” | references/add-network-adapter.md |
| “prove events reach the network” | Step 3 → references/verification.md |
Step 0 — Should this playable emit analytics?
Section titled “Step 0 — Should this playable emit analytics?”AppLovin policy, not a suggestion. Set AnalyticsBootstrap.analyticsEnabled = false and stop
when any of these holds:
- fewer than 3 interactions to complete the playable
- redirects < 5 s after the first interaction
- no win/lose challenge at all (pure interactive demo)
Game shape unclear → AskUserQuestion before wiring anything. A no-challenge playable that tracks
ChallengeStarted violates the pairing rule below and network policy.
Step 1 — Presence check (wired, not just present)
Section titled “Step 1 — Presence check (wired, not just present)”Run all four. A file that exists but is not attached emits nothing, silently.
| # | Check | Command / evidence |
|---|---|---|
| 1 | Package directory present | ls <cocos-project>/assets/packages/@playablelabs/playable-analytics/ |
| 2 | Listed for sync | grep -A 6 playableSync <cocos-project>/package.json → contains @playablelabs/playable-analytics |
| 3 | Attached to a persistent node | grep -n "analyticsEnabled" <cocos-project>/assets/scene/*.scene |
| 4 | Init runs first | bootstrap carries @executionOrder(-1) |
Check 3 is the one that lies. Grepping MainScene.scene for AnalyticsBootstrap returns
zero — the scene stores a compressed cid (__type__ = compressed form of the bootstrap .ts.meta uuid, e.g. "7e304w1bQ9KSLPPW/sHFla3" for uuid
7e304c35-…), not the class name. Grep the serialized property (analyticsEnabled) instead and
confirm _enabled: true. The template attaches it to the Services node.
Attaching a component to a scene node is an editor write → hand it to
t1k-cocos-base-editor-operator; it is not a code edit.
Symptom → cause: a one-time track() called before init() warning in the console means the
bootstrap is not attached. track() still works (the facade lazily self-configures with
defaults) but your editor config — including analyticsEnabled — is ignored. Treat the warning as
“attach the bootstrap”, never as noise.
@executionOrder(-1) is load-bearing: GameView.onLoad() can emit synchronously, so init must
already have run or those first events take the defaults.
Step 2 — Event placement
Section titled “Step 2 — Event placement”Rule: one track() call at a single chokepoint per event. Ask “which moment in my game is
this?” — one answer, one call site. Two call sites for one event double-emit on the paths that hit
both.
Template-owned — already wired, do not duplicate:
| Event | AppLovin | Chokepoint |
|---|---|---|
LoadStart | LOADING | GameView.startLoading() (only when isLoading = true) |
LoadComplete | LOADED | GameView.startGameFlow() after loading |
Displayed | DISPLAYED | GameView.startGameplay() |
ChallengeSolved | CHALLENGE_SOLVED | GameView.onWin() |
ChallengeFailed | CHALLENGE_FAILED | GameView.onLose() |
Game-owned — add per game: ChallengeStarted, ChallengeProgress (25/50/75), ChallengeRetry,
EndCardShown, CtaClicked. Per-event placement + snippets: references/event-placement.md.
Pairing rules — a violation is a broken stream, not a style nit:
LOADING⇒ must also implementLOADED. The AppLovin adapter auto-drops an orphanLOADED, so a strayLoadCompletecan never break the pair.CHALLENGE_STARTED⇒ at least one ofSOLVED/FAILED.- No loading screen ⇒ skip both
LOADINGandLOADED.
Displayed is the only AppLovin-required event. The template ties it to the game-flow step, not
to AllAsyncParametersReadySignal — that signal polls window.mainTheOnePlayable with no timeout
and never fires without the TheOne wrapper, so “wait for ready” would become “never report”. If you
gate Displayed on any readiness signal, add an escape hatch (first interaction and/or a timer).
Guards — never violate these
Section titled “Guards — never violate these”| Guard | Why |
|---|---|
Never call or define window.ALPlayableAnalytics directly | The SDK injects it. Always go through the PlayableAnalytics facade. A test stub is the one exception. |
Never ChallengeFailed from a catch / error / timeout handler | Technical errors, crashes and load failures are not user failure. It is wired only to the genuine loss state. |
Never gate Displayed on a readiness signal without an escape hatch | A poll with no timeout turns “wait for ready” into “never report”. |
ChallengeProgress values other than 25 / 50 / 75 are dropped | Only exact milestones map; anything else is silently discarded. |
Custom is dropped on AppLovin | AppLovin has no custom events. Use it only for a network that supports them. |
Master switch is analyticsEnabled, not enabled | cc.Component already owns enabled — shadowing it is a TS2610 compile error. |
| Dedupe is once-per-session | In-page replay emits nothing the second time. Call PlayableAnalytics.reset() between replays. |
| Never edit the package inside a consumer project | It is a CPM package. Changes go to the package source and a republish — a local edit is lost on the next update. |
| The debug log shows what the facade emitted, not what the network received | It prints before the adapter runs. Use the stubbed-AppLovin path to see the wire. |
Step 3 — Verify
Section titled “Step 3 — Verify”Manual verification, in the editor / browser preview — no build CLI exists. Full checklist with
expected output per path: references/verification.md.
Fastest confidence check — stub the network before interacting:
// paste into the built index.html <head> to reproduce the real injection orderwindow.ALPlayableAnalytics = { _log: [], trackEvent(n) { this._log.push(n); console.log('AL →', n); }};Then play through with isLoading = true and read window.ALPlayableAnalytics._log:
["LOADING", "LOADED", "DISPLAYED", "CHALLENGE_SOLVED"]A CHALLENGE_FAILED in place of CHALLENGE_SOLVED on the lose path is equally correct. For a runtime
pass, route through t1k-gamedev-playable-preview-verify / the t1k-gamedev-playable-runtime-verifier agent.
Hard rules
Section titled “Hard rules”- Check 3 above is the class-name grep trap — the scene stores a compressed cid, so searching
MainScene.sceneforAnalyticsBootstrapreturns 0 lines on a correctly wired project. Verify by the serialized property instead. - A late-injected SDK still receives earlier events. The facade buffers (max 32) and replays in
order once a real adapter appears, and re-probes detection on each
track()until one does. So you can paste the stub mid-session without reloading. forceAdapter: 'noop'is how you test locally without AppLovin;forceAdapter: 'applovin'also disables re-detection..metafiles — a.tscreated outside the editor has no.metauntil the editor imports the folder. No code fix is possible from outside the editor. When copying the package, copy its.metafiles too or Cocos mints new UUIDs and existing scene references break.
Related
Section titled “Related”t1k-cocos-playable-sdk-core— SDK selection, adapter plumbing, CTA routing.t1k-cocos-playable-gameflow— game-flow states and views, where the template chokepoints live.t1k-gamedev-playable-preview-verify/t1k-gamedev-playable-runtime-verifier— runtime verification pass.