Event Tracking

Adlocaite uses a VAST 4.0 compliant event tracking system to record ad playout progress. Instead of a single confirmation call, individual events (start, quartiles, complete) are tracked as they occur -- enabling granular reporting and accurate billing.

Overview

When a screen plays an advertisement, your player fires tracking pixels at defined points during playback. These events are ingested by the Adlocaite Tracking Service and stored per offer for reporting and billing.

OpenRTB loss notices (lurl) for SSP integrations are not handled here; they go to the OpenRTB endpoint, see Loss notifications.

Two integration paths are available:

• VAST players (recommended) -- Request offers with vast=true. The returned VAST XML already contains all tracking pixel URLs, including the correct tracking host, publisher ID and screen ID for the environment you called. Your player fires them automatically during playback and never has to build a tracking URL itself.
• Custom / SDK integration -- Fire tracking events yourself via HTTP, either as individual GET pixel requests or as a batch POST. Use this path only if your player cannot consume VAST. You are then responsible for the host and for the pub and scr parameters described below.

Environments

The Tracking Service runs as a separate host per environment. Events must go to the tracking host that belongs to the API host you requested the offer from.

VAST tracking events

The tracking system supports the following standard VAST events. Each event corresponds to a specific moment during ad playback:

The tracking service also accepts an error event with a code parameter for VAST 4.0 error reporting, but this is not relevant for billing.

Required events for billing

For a playout to be counted as billable, a minimum set of events must be received. This follows the VAST 3.0 minimum standard:

Tracking via VAST pixels

https://tracking.adlocaite.io/track?offer_id={offer_id}&event={event}&ts={timestamp}&pub={publisher_id}&scr={screen_id}

<TrackingEvents>
  <Tracking event="start">
    <![CDATA[https://tracking.adlocaite.io/track
      ?offer_id=550e8400-e29b-41d4-a716-446655440000
      &event=start
      &ts=1710340000000
      &pub=pub-123-uuid
      &scr=screen-456-uuid]]>
  </Tracking>
  <Tracking event="firstQuartile">
    <![CDATA[https://tracking.adlocaite.io/track
      ?offer_id=550e8400-e29b-41d4-a716-446655440000
      &event=firstQuartile
      &ts=1710340000000
      &pub=pub-123-uuid
      &scr=screen-456-uuid]]>
  </Tracking>
  <Tracking event="midpoint">
    <![CDATA[https://tracking.adlocaite.io/track
      ?offer_id=550e8400-e29b-41d4-a716-446655440000
      &event=midpoint
      &ts=1710340000000
      &pub=pub-123-uuid
      &scr=screen-456-uuid]]>
  </Tracking>
  <Tracking event="thirdQuartile">
    <![CDATA[https://tracking.adlocaite.io/track
      ?offer_id=550e8400-e29b-41d4-a716-446655440000
      &event=thirdQuartile
      &ts=1710340000000
      &pub=pub-123-uuid
      &scr=screen-456-uuid]]>
  </Tracking>
  <Tracking event="complete">
    <![CDATA[https://tracking.adlocaite.io/track
      ?offer_id=550e8400-e29b-41d4-a716-446655440000
      &event=complete
      &ts=1710340000000
      &pub=pub-123-uuid
      &scr=screen-456-uuid]]>
  </Tracking>
</TrackingEvents>

curl "https://tracking.adlocaite.io/track?offer_id=550e8400-e29b-41d4-a716-446655440000&event=complete&ts=1710340000000&pub=pub-123-uuid&scr=screen-456-uuid"
# Returns: 1x1 transparent GIF

Tracking via SDK batch

Authorization: Bearer {timestamp}::{hmac_sha256_hex}

curl -X POST "https://tracking.adlocaite.io/track" \
  -H "Authorization: Bearer 1710340000000::a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "offer_id": "550e8400-e29b-41d4-a716-446655440000",
    "publisher_id": "pub-123-uuid",
    "screen_id": "screen-456-uuid",
    "events": [
      { "type": "impression", "timestamp": "2026-03-13T10:00:00Z" },
      { "type": "start", "timestamp": "2026-03-13T10:00:01Z" },
      { "type": "firstQuartile", "timestamp": "2026-03-13T10:00:04Z" },
      { "type": "midpoint", "timestamp": "2026-03-13T10:00:06Z" },
      { "type": "thirdQuartile", "timestamp": "2026-03-13T10:00:09Z" },
      { "type": "complete", "timestamp": "2026-03-13T10:00:11Z" }
    ],
    "player_version": "2.1.0",
    "screen_resolution": "1920x1080"
  }'

{
  "success": true,
  "event_id": "evt-a1b2c3d4-uuid",
  "events_count": 6
}

{
  "error": "Invalid offer_id: must be a valid UUID"
}

{
  "error": "Missing or invalid authorization token"
}

Best practices

Event timing

Fire each tracking event as close to the actual playback moment as possible. The tracking service stores both the client-provided timestamp (ts) and the server receive time (received_at), so large discrepancies between these two values may flag the playout for review.

Retry logic

• GET pixel requests -- Fire-and-forget. If a pixel fails, the VAST standard does not require retries. However, for accurate billing, we recommend retrying failed impression, start, and complete pixels up to 3 times with exponential backoff.
• POST batch requests -- Implement retry with backoff on 5xx responses. 4xx errors indicate a client-side issue (invalid token, malformed body) and should not be retried without fixing the request.

Offline / buffered playback

For screens with intermittent connectivity, buffer events locally and submit them via the POST batch endpoint when connectivity is restored. Include accurate client timestamps so the events can be attributed to the correct playback session.

Performance

• Tracking pixel requests are non-blocking -- they return a 1x1 GIF immediately and process asynchronously
• For high-volume setups with many screens, prefer the POST batch endpoint to reduce HTTP overhead
• Set reasonable timeouts (3-5 seconds) for pixel requests to avoid blocking your content pipeline

Deprecated: playout/confirm

# Don't use this anymore
curl -X POST "https://api.adlocaite.com/functions/v1/api/playout/confirm/DEAL_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "played_at": "2026-03-13T14:30:00Z",
    "duration_seconds": 15,
    "completion_rate": 100
  }'

# Request offer with VAST
curl "https://api.adlocaite.com/functions/v1/api/offers/request/SCREEN_ID?vast=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Player automatically fires pixels from VAST XML:
# impression, start, firstQuartile, midpoint,
# thirdQuartile, complete

# Fire events individually. pub and scr are required;
# use the tracking host of your environment (see Environments).
curl "https://tracking.adlocaite.io/track?offer_id=OFFER_ID&event=impression&ts=$(date +%s000)&pub=PUBLISHER_ID&scr=SCREEN_ID"
curl "https://tracking.adlocaite.io/track?offer_id=OFFER_ID&event=start&ts=$(date +%s000)&pub=PUBLISHER_ID&scr=SCREEN_ID"
# ... playback happens ...
curl "https://tracking.adlocaite.io/track?offer_id=OFFER_ID&event=complete&ts=$(date +%s000)&pub=PUBLISHER_ID&scr=SCREEN_ID"

{
  "success": true,
  "deprecated": true,
  "message": "This endpoint is deprecated and will be removed after 2026-06-01. Playout tracking now happens automatically via VAST tracking pixels.",
  "deal_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}