Telemetry schema 1 → 2

Telemetry batches moved from schema version 1 to 2 on 2026-11-03. The one change: the batch context names the app the licence key belongs to.

Since 0.1

Who is affected

Two kinds of integration see a difference. Anything that sends telemetry batches itself, rather than through the PB Play player or an SDK, sees a new field to send. Anything that loads warehouse export files sees one more column. If you only embed the player and read analytics in the dashboard, nothing changes for you: the player sends version 2 on its own.

What changed

The batch context gained app: the opaque id of the app the key belongs to, taken from the manifest's app, or none when the key has no app and in unlicensed mode. Sessions and rollups now carry app, and rollups are grouped by it.

{
  "schemaVersion": 1,
  "context": { "property": "…", "media": "…", "player": "…", "session": "…", … },
  "events": [ … ]
}
{
  "schemaVersion": 2,
  "context": { "property": "…", "app": "<app id, or none>", "media": "…", "player": "…", "session": "…", … },
  "events": [ … ]
}

What keeps working

Ingest accepts schema versions 1 and 2 for one deprecation window, because SDKs already shipped keep sending version 1 for their lifetime. A version 1 batch, or a version 2 batch without app, is stored as app: 'none' — counted together with keys that have no app, not dropped.

In warehouse export, app was added as the last column, after ad_completes. A load job that reads columns by position reads exactly what it read before, plus one more column at the end.

What to do

  1. If you send batches yourself, set schemaVersion to 2 and add app to the context — the manifest's app, or none.
  2. If you load warehouse export files by column name, add an app column to your table. If you load by position, add it as the last column so the extra field lands somewhere.
  3. If you group or filter rollups, decide whether reports should now split by app; rows with no app read none.

How to tell it worked

The last two columns of an export row are ad_completes, app, and a batch you send with schemaVersion: 2 is accepted rather than refused.