Programmatic

Passing Custom KVPs & Dynamic Macros in DV360 VAST Tags

November 4, 2026

To pass custom key-value pairs (KVPs) and dynamic macros in DV360 VAST tags for DCO, append custom query parameters using DV360 ${MACRO_NAME} syntax directly to your dynamic creative ad server’s VAST URL. During an auction, DV360 dynamically evaluates these macros and passes context—such as Line Item ID, Exchange ID, or Geo Zip—to the ad server, enabling real-time video personalization.

Key Takeaways

  • Syntax precision is mandatory: DV360 requires the ${MACRO_NAME} format, whereas Campaign Manager 360 (CM360) uses %m or pattern macros; using the wrong syntax results in unexpanded literal strings.
  • Query string formatting dictates DCO execution: Append custom parameters to the VAST URL using standard URL encoding, separating keys and values with equal signs (key=${MACRO}) and chaining them with ampersands (&).
  • Bulk deployment saves hours: Use DV360 Structured Data Files (SDF) to programmatically edit VAST tag URLs across hundreds of line items instead of updating tags manually in the UI.
  • Validation requires HTTP proxy tools: Rely on network inspection tools like Charles Proxy or Fiddler to confirm macro expansion in actual VAST response payloads before pushing campaigns live.

What Are DV360 Dynamic Macros and How Do They Power Video DCO?

Dynamic Creative Optimization (DCO) for video relies on sending immediate inventory and user context to a dynamic decisioning engine (such as Google Studio, Innovid, Flashtalking, or Clinch) before rendering the ad payload. In Display Video 360 (DV360), dynamic macros act as variables placed inside VAST tag URLs. When an ad request originates from an ad placement, DV360 replaces these placeholder variables with real-time impression data.

Without dynamic macros, dynamic video creative platforms must rely solely on the IP address or publisher-provided signals extracted at runtime. By explicitly passing variables in the VAST request URL, you give your dynamic creative engine granular metadata from the DSP bid stream. This metadata allows the creative engine to serve tailored video frames, customized audio overlays, or location-specific end cards instantly.

Understanding the architecture of a dynamic VAST request is crucial. When DV360 wins an auction, it executes a call to the video ad server (VAST wrapper call). The ad server receives the request, parses the query string parameters, feeds those key-value pairs into its internal decision matrix, and returns a tailored VAST XML response containing the exact media file (MP4/HLS) matched to those parameters.

Standard DV360 Macros for VAST Tags

DV360 supports native macros that populate structural, context, and targeting parameters into VAST tag URLs. The table below outlines the core system macros used in DCO video workflows.

DV360 Macro Syntax Variable Expanded Primary DCO Use Case Supported Channel
${CAMPAIGN_ID} DV360 Campaign ID Cross-campaign creative rules & reporting aggregation Display, Video, CTV
${INSERTION_ORDER_ID} DV360 Insertion Order ID Budget-tier specific offer mapping Display, Video, CTV
${LINE_ITEM_ID} DV360 Line Item ID Targeting-strategy specific creative decisioning Display, Video, CTV
${CREATIVE_ID} DV360 Creative Asset ID Creative performance tracking and dynamic variant verification Display, Video, CTV
${EXCHANGE_ID} SSP / Exchange ID Publisher-family specific creative adaptations Display, Video, CTV
${CACHEBUSTER} Random Numerical String Prevents ad server VAST response caching Display, Video, CTV
${DEVICE_TYPE} Device Category Code Swapping dynamic aspect ratios or CTA layouts (Mobile vs CTV) Display, Video, CTV

Note that CM360 and DV360 handle macro syntax differently. If your VAST tags are generated in CM360 and wrapped for DV360, you must distinguish between macros evaluated by CM360 at impression time and those passed down to DV360 for real-time DSP-level evaluation.

How to Construct Custom Key-Value Pairs in DV360 VAST Tag URLs

Constructing custom Key-Value Pairs (KVPs) requires structuring the dynamic VAST tag URL so that your dynamic creative platform can easily parse the query parameters. Every custom KVP consists of a parameter key expected by the DCO server and a DV360 macro as the parameter value.

1. Structural Anatomy of a Dynamic VAST Tag URL

A standard raw 3rd-party VAST URL looks like this before adding custom parameters:

https://ad.doubleclick.net/ddm/pfadx/N123456.site/B9876543;sz=0x0;ord=123456789?

To pass custom dynamic data for DCO execution, append custom query parameters after the question mark (?) or semi-colon delimitation depending on the ad server architecture. For standard third-party VAST endpoints (e.g., Flashtalking or Innovid), use standard URI query parameters:

https://serv.flashtalking.com/video/vast/1234?ft_li=${LINE_ITEM_ID}&ft_io=${INSERTION_ORDER_ID}&ft_ex=${EXCHANGE_ID}&ft_cb=${CACHEBUSTER}

2. URL Character Encoding Rules

When passing macro values that might resolve into strings containing spaces, slashes, or special characters (such as custom contextual key-values or site names), wrap the macro inside an encoding wrapper: ${URL_ENC(...)}.

For example, if you are passing custom contextual segment names to an ad server that requires strict URL encoding:

https://dco.adserver.com/vast?category=${URL_ENC(CATEGORY_NAME)}&li=${LINE_ITEM_ID}

Failing to encode dynamic parameters can break the query string. This results in bad request errors (HTTP status 400) or corrupt VAST XML nodes, which prevents the video player from rendering the ad unit.

Step-by-Step Guide: Setting Up Dynamic VAST Tags in DV360

Follow these steps to deploy dynamic VAST tags with custom KVPs in DV360.

Step 1: Obtain the Master VAST Tag Template from Your DCO Provider

Request the dynamic VAST URL template from your DCO team or ad serving vendor. Verify that the parameter keys in the tag match the schema configured in the creative decisioning matrix. If the DCO platform expects dco_li for the Line Item ID, ensure your key matches that exact string.

Step 2: Format the DV360 Macros

Replace generic placeholders provided by your creative vendor with DV360 dynamic macro syntax. Convert format styles like [LINE_ITEM_ID] or %%LINE_ITEM_ID%% into ${LINE_ITEM_ID}.

Step 3: Upload the VAST Tag into DV360 Creative Module

  1. Navigate to your Advertiser in DV360.
  2. In the left menu, select Creatives > Format Management or Creatives.
  3. Click New > Third-Party Video (VAST).
  4. Enter a clear Creative Name that includes the creative version and DCO tag indicator.
  5. Paste your fully formatted VAST URL into the VAST Tag URL field.
  6. Set the duration, select the video format (In-Stream, Out-Stream), and configure your fallback assets if required.

Step 4: Execute Bulk Tag Editing via SDF

For large-scale video campaigns across dozens of line items, manually appending KVPs to every tag in the UI is inefficient. Learn how to leverage SDF files in our How to Bulk Edit DV360 Line Items: UI, SDF & API Guide. You can export Line Item or Creative SDF sheets, modify the VAST Tag URL column in bulk by concatenating dynamic query strings, and re-upload the updated sheet to DV360 instantly.

Advanced DCO Scenarios: Geo, Exchange, and Contextual Signal Passing

Advanced DCO execution often relies on passing signals beyond standard database identifiers. Here is how to configure VAST tags for complex dynamic use cases.

1. Localized Dynamic Video Delivery via Location KVPs

While dynamic creative servers can resolve location via user IP, proxy anonymization and CTV network aggregation can cause IP geotargeting mismatches. Passing the targeted location explicitly using internal identifiers ensures strict consistency across your ad stack.

Construct your VAST URL to pass exchange-level geo parameters:

https://v.dco-engine.com/vast?campaign=${CAMPAIGN_ID}&zip=${GEO_ZIP}&li=${LINE_ITEM_ID}

When the bid engine executes the VAST call, the exact zip code associated with the bid request is injected directly into the dynamic creative engine. This enables instantaneous localized frame swapping—such as displaying the nearest store location or local pricing—without relying on external IP lookup tables.

2. Supply-Path Tailored Creative Execution

Different SSPs and publishers enforce unique video playback standards, aspect ratio rules, and duration caps. Passing the SSP source parameter via ${EXCHANGE_ID} allows your dynamic creative ad server to adjust bitrate tiers or render specific call-to-action overlays tailored to the inventory source.

For connected TV inventory where exchange signal passing aligns directly with supply-path optimization, combine your VAST macro strategy with DV360 Custom Bidding for CTV SPO to optimize bid valuation alongside creative rendering.

Appending ex=${EXCHANGE_ID} to the VAST URL gives the creative engine full visibility into the supply path for every impression:

https://engine.innovid.com/vast/1a2b3c?ssp=${EXCHANGE_ID}&li=${LINE_ITEM_ID}&dev=${DEVICE_TYPE}

Debugging Common VAST Tag Macro Failures in Ad Ops

Dynamic VAST integrations can fail due to string formatting errors, syntax typos, or missing parameter values. Use the following troubleshooting checklist to diagnose issues quickly.

1. Literal Unexpanded Macros in Dynamic Reports

If your DCO reporting dashboard shows ${LINE_ITEM_ID} as a literal text string instead of numerical IDs (e.g., 102938475), the macro syntax is invalid. This issue typically occurs when:

  • CM360 macros (e.g., %m) were entered into a direct DV360 VAST upload without CM360 wrapper translation.
  • The macro was misspelled (e.g., ${LINEITEM_ID} missing the middle underscore).
  • The VAST tag was hardcoded inside an iFrame container that prevented DSP token evaluation.

2. VAST Error 303 & Parsing Failures

When unexpanded macros or unescaped characters corrupt the XML structure, SSPs frequently throw wrapper timeout or empty response errors. Refer to our guide to Fix VAST Error 303 in DV360 Video & CTV Campaigns to isolate ad server response issues.

To verify if invalid character encoding in custom KVPs is causing VAST XML parsing failures, capture the live request using an HTTP traffic analyzer. Copy the populated VAST URL directly from the bid stream logs and paste it into a web browser. If the response displays invalid XML syntax or a broken <VAST> root node, evaluate your dynamic key-value parameters for unencoded spaces, special symbols, or missing ampersands.

3. Cache-Busting Failures Leading to Dynamic Stale Renders

If a video player caches the initial VAST tag response, subsequent requests from the same user or device will serve the initial creative render, ignoring updated dynamic KVPs. Always append ord=${CACHEBUSTER} or cb=${CACHEBUSTER} to the dynamic VAST request string. The ${CACHEBUSTER} macro injects a random numerical string into every request, forcing the publisher's video player to fetch a fresh dynamic VAST payload for every single auction.

Frequently Asked Questions

How do you verify if DV360 system macros are expanding correctly in VAST tags?

To verify macro expansion, generate a live preview link in DV360 or inspect the network calls of a test impression using web developer tools or an HTTP proxy like Charles. Look at the outgoing VAST XML request URL under the Network tab and verify that macros such as ${LINE_ITEM_ID} have been replaced by real numerical values instead of raw text strings.

Why are custom KVPs showing as unexpanded string literals in dynamic creative reports?

Custom KVPs appear as unexpanded string literals when the macro syntax does not match the engine evaluating the tag. If a tag is Trafficked natively in DV360, it must use the ${MACRO_NAME} format; if it is routed through CM360, it requires CM360 pattern macros. Syntax typos or unescaped special characters can also prevent the DSP parser from recognizing the macro string.

Can you pass custom audience segment IDs through VAST macros in DV360?

DV360 does not offer a native macro that explicitly extracts third-party or first-party audience segment IDs directly into VAST tags for privacy reasons. However, you can pass targeted audience context by organizing your campaign line items by audience segment and passing the ${LINE_ITEM_ID} to your DCO engine, which maps that specific Line Item ID to the target audience segment in its internal database.

What is the difference between CM360 VAST macros and DV360 native macros?

CM360 VAST macros use percent-delimited or pattern syntax (such as %m or [timestamp]) and are evaluated by Campaign Manager 360 when serving the ad. DV360 native macros use the ${MACRO_NAME} syntax and are evaluated in real time by the DV360 buying engine at the moment of the programmatic bid request, capturing real-time DSP-level variables.