Prebid.js Video Ad Handling: Complete Flow Logic

gistfile1.txt

# Prebid.js Video Ad Handling: Complete Flow Logic

## Overview

This document explains how Prebid.js handles video ads with different combinations of:
- Cache settings (enabled vs. disabled)
- Video types (instream vs. outstream)
- VAST representations (vastUrl vs. vastXml)

## Key Components

1. **Video Cache**: Optional service that stores VAST XML, providing a universal key for ad servers
2. **VAST Formats**:
   - `vastUrl`: URL pointing to a VAST XML document
   - `vastXml`: The complete VAST XML as a string
3. **Video Types**:
   - **Instream**: Video ads that play within a video player (pre-roll, mid-roll, post-roll)
   - **Outstream**: Video ads that play outside of a video player (in-article, in-banner, etc.)

## Complete Flow Logic

### Scenario 1: Cache Enabled, Instream Video

When the publisher has enabled Prebid Cache and the video format is instream:

1. **Bid Processing**:
   - If both `vastUrl` and `vastXml` are present:
     - Prebid core has a slight bias toward using `vastXml`
     - In `videoCache.js`, we check for `vastXml` first
   - If only one format exists, Prebid uses what's available

2. **Caching Process**:
   - If `vastXml` is present:
     - Send the `vastXml` directly to Prebid Cache
   - If only `vastUrl` is present:
     - Wrap the `vastUrl` in stock VAST-wrapper code to create a VAST XML
     - Send this wrapper VAST XML to Prebid Cache
   
3. **Results**:
   - Prebid Cache returns a `videoCacheKey`
   - This key is added to the bid object
   - The ad server (e.g., GAM) uses this key in the ad request

### Scenario 2: Cache Disabled, Instream Video

When Prebid Cache is disabled and the video format is instream:

1. **Bid Processing**:
   - If both `vastUrl` and `vastXml` are present:
     - Bid is accepted by Prebid core
   - If only `vastUrl` is present:
     - Bid is accepted by Prebid core
   - If only `vastXml` is present:
     - **Bid is rejected** by Prebid core
     
2. **Ad Server Video Module Behavior** (e.g., dfpAdServerVideo):
   - When using `vastUrl`:
     - The `vastUrl` is encoded and included as `description_url` parameter
   - The `vastXml` is not directly used in this scenario

### Scenario 3: Outstream Video (Cache Enabled or Disabled)

For outstream video, the cache setting is less relevant:

1. **Renderer Check**:
   - Primary validation is for a `renderer` object in either:
     - The bid object itself
     - The bidRequest/adUnit
   - If renderer is missing, the bid is rejected

2. **Rendering Process**:
   - The renderer is responsible for reading either:
     - `vastUrl`
     - `vastXml`
     - Or possibly a custom field specific to the bidder
   - Outstream videos do not rely on Prebid Cache for rendering
   - The renderer handles the actual display of the video ad in the page

## Important Notes

- For instream videos with cache disabled, bids with only `vastXml` are rejected
- Prebid core shows a slight preference for `vastXml` when both formats are present
- Outstream videos focus primarily on the presence of a renderer, not the VAST representation
- The dfpAdServerVideo module specifically uses `vastUrl` (as description_url) when cache is disabled