Skip to content

t1k:cocos:playable:analytics

FieldValue
Moduleplayable
Version4.33.13
Effortmedium
Tools—

Keywords: ALPlayableAnalytics, analytics, applovin analytics, event tracking, playable events, PlayableAnalytics, PlayableEvent, track event

/t1k: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).

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

#CheckCommand / evidence
1Package directory presentls <cocos-project>/assets/packages/@playablelabs/playable-analytics/
2Listed for syncgrep -A 6 playableSync <cocos-project>/package.json → contains @playablelabs/playable-analytics
3Attached to a persistent nodegrep -n "analyticsEnabled" <cocos-project>/assets/scene/*.scene
4Init runs firstbootstrap 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.

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:

EventAppLovinChokepoint
LoadStartLOADINGGameView.startLoading() (only when isLoading = true)
LoadCompleteLOADEDGameView.startGameFlow() after loading
DisplayedDISPLAYEDGameView.startGameplay()
ChallengeSolvedCHALLENGE_SOLVEDGameView.onWin()
ChallengeFailedCHALLENGE_FAILEDGameView.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 implement LOADED. The AppLovin adapter auto-drops an orphan LOADED, so a stray LoadComplete can never break the pair.
  • CHALLENGE_STARTED ⇒ at least one of SOLVED / FAILED.
  • No loading screen ⇒ skip both LOADING and LOADED.

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

GuardWhy
Never call or define window.ALPlayableAnalytics directlyThe SDK injects it. Always go through the PlayableAnalytics facade. A test stub is the one exception.
Never ChallengeFailed from a catch / error / timeout handlerTechnical 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 hatchA poll with no timeout turns “wait for ready” into “never report”.
ChallengeProgress values other than 25 / 50 / 75 are droppedOnly exact milestones map; anything else is silently discarded.
Custom is dropped on AppLovinAppLovin has no custom events. Use it only for a network that supports them.
Master switch is analyticsEnabled, not enabledcc.Component already owns enabled — shadowing it is a TS2610 compile error.
Dedupe is once-per-sessionIn-page replay emits nothing the second time. Call PlayableAnalytics.reset() between replays.
Never edit the package inside a consumer projectIt 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 receivedIt prints before the adapter runs. Use the stubbed-AppLovin path to see the wire.

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

  • Check 3 above is the class-name grep trap — the scene stores a compressed cid, so searching MainScene.scene for AnalyticsBootstrap returns 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.
  • .meta files — a .ts created outside the editor has no .meta until the editor imports the folder. No code fix is possible from outside the editor. When copying the package, copy its .meta files too or Cocos mints new UUIDs and existing scene references break.
  • 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.