@handler/playable-sdk

Contract-aligned Handler Playable SDK v0.1. Surface is fixed: init, getRoot, on, off, start, finish, install, emit. Provides a single root sandbox, canonical event envelope, and ID requirements for publish builds.

API (v0.1)

• Handler.init({ root?, ids, profile, consent }): creates or adopts a single root. ids must include mechanic_id, variant_id, deployment_id, export_id, profile_id, instance_id (instance default “default” only allowed in dev). Consent/telemetry pulled from export profile.
• Handler.getRoot(): returns the sandbox root element.
• Handler.on(name, cb), Handler.off(name, cb): subscribe/unsubscribe to canonical events or custom namespaced ones.
• Handler.start(), Handler.finish(): lifecycle markers.
• Handler.install(url?): emits cta_click and, if profile policy demands, conversion. Direct network open is deferred to capability policy.
• Handler.emit(name, payload): emits canonical or namespaced custom events. Reserved envelope keys are always added/overwritten.

Canonical event mapping from Smoud: interaction -> engagement, finish -> complete, install -> cta_click (+conversion policy), pause/resume/resize/volume mapped 1:1 inside the envelope. Custom events must use custom.<mechanic_id>.<event>.

Build

npm run build

Outputs ESM/CJS + d.ts to dist/.

License

MIT