Player Event API V2
Event collector for ODK Media players and clients. One service, three route families, routed by path:
| Route family | Path | Wire s | Landing |
|---|---|---|---|
| Player Events v2 (ODK) | /api/v2/odk/{playlist,firstplay,viewhour} | server stamps s=odk | raw_odkr_* |
| Telemetry | POST /telemetry/event | envelope service field | raw_telemetry_* |
| Player Events v2 (Amasian legacy) | /api/v2/{playlist,firstplay,viewhour} | client-sent s | raw_amasian_* |
Hosts — the same build serves every host; hostnames are the future migration unit.
| Env | ODK player events | Telemetry | Amasian legacy |
|---|---|---|---|
| staging | https://pe-odk-stg.odkmedia.io | https://pe-t-stg.odkmedia.io | https://pe-stg.odkmedia.io |
| production | https://pe-odk.odkmedia.io | https://pe-t.odkmedia.io | unchanged |
Session model (all player-event routes): playlist is called once per playback session and returns a server-issued
stream_session_id (ss). firstplay and viewhour carry that ss. A client-sent ss on playlist is ignored.
Validation model: only missing required parameters return 422. Every other declared parameter is documentation:
values are stored as strings exactly as sent, never rejected for shape. Undeclared query parameters are stored too.
Data-quality checks live in the warehouse, not here.
Client contract for ODK teams: odk_client_spec.md v2 (Jira BEE-5211 / BEE-5228). Field semantics: PM spec
"Player Events fields description v2.1.5" (Confluence 4369186820).
s=odk on every event regardless of what the client sends. Send s=odk, did, osdid, and mci (vod/shorts/short_drama) or ch (live/multiview) on all three events. No Continue Watching side effects.events[]. The envelope service is the one validated field: it must be one of odk, amasian, otherwise 400 with no row — an unknown service would land rows under the wrong service. An accepted request returns 202. Event types outside the allow-list (default visit, heartbeat, view, env TELEMETRY_EVENT_TYPES; the live list is on the route) and malformed events are kept and routed to the unknown quarantine table./api/v2/* routes used by Amasian clients. Behaviour unchanged. Requires s on playlist; drives Continue Watching (Redis) when mci and did or u are present: a signed-in viewer's u (the Amasian user uuid) saves it to the account, otherwise it is saved to the device.