Track a batch of buffered device playbacks

POST

/v1alpha2/track:batch

Drain a buffer of fires. Build each entry by splitting the buffered URL’s query string into an object of its parameters — every parameter, unchanged, including any the player does not recognize — then appending ets, except on an error. Never rename, reformat, drop or compute a parameter. On 200, clear the whole batch from the buffer. On 5xx, retry the whole batch: a replayed play is counted once, so a retry never double-counts a play. Entries listed in rejected were malformed; log and drop them, never retry.

Request Body

ExposureTrackBatchRequest carries a drained offline buffer: many fires in one request. Each entry is a complete Track request, built by splitting a buffered URL’s query string into an object of its parameters.

Media typeapplication/json

ExposureTrackBatchRequest carries a drained offline buffer: many fires in one request. Each entry is a complete Track request, built by splitting a buffered URL’s query string into an object of its parameters.

object

fires

Fires are the buffered fires, in any order — the server groups them itself, so the player sends a flat list and never restructures its queue. Copy every parameter of each buffered URL through, including any the player does not recognize; dropping one silently loses what it carried.

Array<object>

ExposureTrackRequest reports a single playback fire. The URL and all query parameters are server-stamped; players must relay the URL verbatim, appending only ets (occurrence time). Never parse or modify any server-provided param.

object

asid

Asid is the per-serving id (the ad-serving id; the decision-store key) stamped on the tracking URLs by Exchange.Ads.

string

ae

ad_event carries an ad-level event marker (e.g. "impression"). Proto field name is the GET query param (?ae=...)

string

ce

creative_event carries a creative-level event marker (e.g. "start"). Proto field name is the GET query param (?ce=...)

string

sts

Sts is the Verve server timestamp stamped at decision time (RFC3339).

string

ets

Ets is the player-side event occurrence timestamp (RFC3339). Optional with ce=error.

string

dvactid

Dvactid is the opaque Advertima activation id.

string

flight_id

The following are offline-fire enrichment params: present only on offline self-resolving fires, absent on online fires (which resolve via asid lookup). The handler branches on their presence (dual-shape decode). flight_id is the booked flight behind the decision.

string

campaign_id

Campaign_id is the campaign behind the decision.

string

request_id

Request_id groups the ads served by one /ads response.

string

source

Source is the supply kind behind the decision (a Source* kind).

string

creative_id

Creative_id is the served creative/asset id.

string

location_id

Location_id is the place the device is located in (offline attribution).

string

device_id

Device_id is the player/screen that rendered the ad (offline attribution).

string

flight_revision

Flight_revision is the flight resource revision id at decision time.

string

error_code

Error_code is the VAST error code the player puts in place of the [ERRORCODE] macro. Sent with ce=error only.

string

Example^generated

{
  "fires": [
    {
      "asid": "example",
      "ae": "example",
      "ce": "example",
      "sts": "example",
      "ets": "example",
      "dvactid": "example",
      "flight_id": "example",
      "campaign_id": "example",
      "request_id": "example",
      "source": "example",
      "creative_id": "example",
      "location_id": "example",
      "device_id": "example",
      "flight_revision": "example",
      "error_code": "example"
    }
  ]
}

Responses

200

A successful response.

Media typeapplication/json

ExposureTrackBatchResponse reports what the server took. HTTP 200 means the batch itself was well-formed, not that every event reached the pipeline: an expired or unknown asid is accepted here and dropped afterwards, exactly as it is on a single Track fire.

object

accepted

Accepted is how many fires were handed to the pipeline. Not a delivery receipt; see the message comment.

integer format: int32

rejected

Rejected lists the malformed entries. These are 400-class and will never succeed, so log and drop them — retrying one only repeats the rejection. Everything not listed here is counted in accepted.

Array<object>

RejectedFire names one entry the server would also have refused as a single Track fire — a missing asid, a missing ets (not on an error), an unparseable ets, or an unrecognized event marker.

object

index

Index is the entry’s position in the request’s fires.

integer format: int32

reason

Reason is human-readable, for the player’s log. Do not branch on it: the wording is not part of the contract.

string

Example^generated

{
  "accepted": 1,
  "rejected": [
    {
      "index": 1,
      "reason": "example"
    }
  ]
}