Docs/SSAI/Measurement Semantics

Measurement & Tracking Semantics

How ApexMediation SSAI tracks impressions, quartiles, and completion events. Definitions, exactly-once semantics, and reconciliation guidance.

Core Guarantee: Exactly-Once Delivery

Each tracking event is fired exactly once per ad view. Retries are deduplicated server-side. Late events (beyond the session TTL) are logged but not delivered.

Event Definitions

Event	Trigger Condition	Live Mode	VOD Mode
Impression	First segment of ad loaded	Segment fetch from CDN	Segment fetch from CDN
Start	Playback begins (first byte)	Player reports play event	Player reports play event
First Quartile	25% of ad duration played	Time-based (segment count)	Time-based (segment count)
Midpoint	50% of ad duration played	Time-based	Time-based
Third Quartile	75% of ad duration played	Time-based	Time-based
Complete	100% of ad duration played	Last segment fetched	Last segment fetched
Skip	User skips (if enabled)	N/A (SSAI ads not skippable)	Optional feature
Error	Playback failure	Segment 404 or timeout	Segment 404 or timeout

Note on Segment-Based Tracking

SSAI tracks based on segment fetches, not player-reported time positions. This is more reliable because segment requests are observable server-side. For a 30-second ad with 2-second segments, quartile triggers occur at segments 4, 8, 12, and 15.

Deduplication Keys

Each tracking event is uniquely identified by a composite key that ensures exactly-once delivery:

// Dedupe key format
{session_id}:{ad_id}:{position_in_pod}:{event_type}

// Example
"sess_a1b2c3:ad_xyz789:0:firstQuartile"

// Components:
//   session_id      - Unique viewer session (UUID)
//   ad_id           - Creative identifier from demand partner
//   position_in_pod - 0-indexed position of ad in the break
//   event_type      - impression|start|firstQuartile|midpoint|thirdQuartile|complete|error

Dedupe Behavior

• First event with key → delivered
• Duplicate within TTL → silently dropped
• Duplicate after TTL → logged as "late"
• TTL: 24 hours for VOD, 4 hours for Live

Retry Behavior

• Initial delivery → immediate
• First retry → 500ms delay
• Second retry → 2s delay
• Third retry → 10s delay (final)
• Max retries: 3 per event

Live vs VOD Tracking Differences

Live Mode

●Real-time tracking: Events fired as segments are fetched (sub-second latency)
●Session TTL: 4 hours (covers typical live viewing session)
●Seek handling: Seeks within ad break don't re-fire events (dedupe)
●DVR playback: Events fire on DVR catch-up if within TTL
●Pause handling: Paused session still valid, events fire on resume

VOD Mode

●Segment-based tracking: Events mapped to pre-computed segment positions
●Session TTL: 24 hours (covers multi-day binge watching)
●Resume position: Tracked; events only fire for unwatched segments
●Re-watch: Same session → no duplicate events. New session → full event set.
●Fast-forward: Skipped segments don't trigger quartile events

Late Event Handling

Events that arrive after the session TTL are considered "late" and handled specially:

Late Event Policy

What happens:

• Event logged to late_events table
• Not delivered to demand partners
• Not counted in primary metrics
• Available in reconciliation reports

Common causes:

• Client offline then reconnects
• Aggressive browser sleep mode
• Network outage during playback
• SDK retry after long delay

Typical late event rate: <0.1% of total events. Spikes indicate client SDK issues or network problems.

Reconciliation & Reporting

For billing and partner reconciliation, we provide detailed event exports:

Export Fields

{
  "event_id": "evt_abc123",
  "session_id": "sess_xyz789",
  "ad_id": "creative_456",
  "demand_partner": "partner_a",
  "event_type": "complete",
  "timestamp": "2024-01-15T14:30:00Z",
  "delivered_at": "2024-01-15T14:30:00.150Z",
  "delivery_latency_ms": 150,
  "retry_count": 0,
  "dedupe_status": "first",  // first | duplicate | late
  "client_ip_hash": "sha256:...",
  "user_agent_category": "ctv_roku",
  "geo_country": "US",
  "geo_region": "CA"
}

Daily Export

Full event log for previous day. Available by 06:00 UTC.

Real-time API

Query events by session, ad, or time range. 15-minute delay.

Discrepancy Report

Partner-side vs our-side event diff. Weekly summary.

Common Discrepancy Causes

Our count higher than partner

• Partner filtering by viewability (we count segment fetch)
• Partner has stricter fraud filtering
• Timezone mismatch in daily rollup

Our count lower than partner

• Partner counting client-side (double-fires)
• Partner not deduplicating retries
• Test traffic included in partner count

Expected variance

±2% variance is normal due to timing differences, timezone rollups, and edge cases. Variance >5% triggers automatic investigation.