Playout Tracking

Playout tracking allows you to confirm when advertisements have been successfully displayed on your screens. This is essential for accurate reporting, billing, and advertiser verification in programmatic DOOH advertising.

What is playout tracking?

After you accept an offer and receive a deal_id, your screen displays the advertisement. Once the ad has finished playing, you should call the playout confirmation endpoint to:

• Confirm successful display - Verify the ad was actually shown
• Enable accurate reporting - Track real impressions vs. deals
• Ensure proper billing - Publishers get credited for confirmed playouts
• Provide advertiser transparency - Proof of performance

The playout confirmation model

The playout confirmation request allows you to provide detailed information about how the advertisement was displayed.

Properties

Confirm a playout

curl -X POST "https://api.adlocaite.com/functions/v1/api/playout/confirm/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "success": true,
  "playout_id": "playout_1729426192_abc123def",
  "deal_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "played_at": "2025-10-10T14:30:00Z",
  "duration_seconds": 15,
  "completion_rate": 100,
  "player_version": "AdlocaitePlayer v2.1.3",
  "screen_resolution": "1920x1080",
  "message": "Playout confirmed successfully"
}

{
  "success": true,
  "playout_id": "test-playout-1729426192874",
  "deal_id": "test-deal-test",
  "played_at": "2025-10-10T14:30:00Z",
  "message": "Demo playout confirmed successfully"
}

{
  "error": "Missing or invalid authorization header. Use: Bearer <publisher_api_key>"
}

{
  "error": "Invalid JSON in request body"
}

{
  "error": "Deal not found or access denied"
}

VAST integration

When you request offers with vast=true, the returned VAST XML automatically includes playout tracking URLs. Modern programmatic players can use these to automatically call the playout confirmation endpoint.

VAST tracking events

The VAST XML includes a special playout tracking event:

<TrackingEvents>
  <Tracking event="complete">
    <![CDATA[https://tracking.adlocaite.com/track?offer_id=...&event=complete]]>
  </Tracking>
  <Tracking event="playout">
    <![CDATA[https://api.adlocaite.com/playout/confirm/deal-id-here]]>
  </Tracking>
</TrackingEvents>

Automatic vs. manual confirmation

Best practices

When to confirm playouts

Error handling

Always implement proper error handling for playout confirmations:

// Example: Retry logic for playout confirmation
async function confirmPlayout(dealId, playoutData, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(`/api/playout/confirm/${dealId}`, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(playoutData)
      });
      
      if (response.ok) {
        console.log('Playout confirmed successfully');
        return await response.json();
      }
    } catch (error) {
      console.warn(`Playout confirmation attempt ${attempt} failed:`, error);
      if (attempt === maxRetries) {
        console.error('All playout confirmation attempts failed');
      }
    }
  }
}

Performance considerations

• Non-blocking: Make playout confirmation calls asynchronously to avoid delaying your content pipeline
• Batch processing: For high-volume screens, consider batching multiple confirmations
• Timeout handling: Set reasonable timeouts (5-10 seconds) for confirmation requests
• Offline handling: Cache confirmations if network connectivity is poor and retry later

Monitoring and debugging

Use the optional fields to help with monitoring and debugging:

• player_version: Track which player versions have issues
• screen_resolution: Identify resolution-specific problems
• completion_rate: Monitor ad completion rates across screens
• duration_seconds: Compare actual vs. expected playout times