Skip to content
All field notes
Measurement
Published
Nov 1, 2026
Reading time
11 min read

VAST Macros Not Resolving: Inspect the Actual Request

Trace VAST macros from tag templates to emitted requests and receiver values. Diagnose substitution ownership, unsupported placeholders and encoding errors.

AP
AdProof Research
Independent measurement desk
A VAST URL template passes through a substitution gate before a loupe compares its emitted request with a separate receiver-parsing record.
The template, outgoing URI and receiver's parsed value provide different evidence. Conceptual illustration.
In this guide (10 sections)

To see what a VAST macro became, inspect the HTTP request made by the system responsible for substitution. Compare its actual URI with the template that system received and, where available, the receiver's parsed value. A placeholder in saved VAST can be expected before substitution; a placeholder surviving into the request needs a different investigation.

For browser-side requests, Chrome's Network panel can expose the emitted URI. For server-side ad insertion, obtain the corresponding server evidence. Browser traffic alone cannot show an HTTP call made elsewhere. Preserve both the encoded representation and the decoded value before changing tags.

Two older questions reveal the diagnostic gap#

An archived ad-operations question asks whether populated VAST macros can be viewed. A reply recommends filtering browser Network requests. That is a useful starting point, but it leaves substitution ownership, server-side requests and receiver interpretation unexplained.

A 2016 Stack Overflow question about Google IMA tracking macros asks how to reproduce several SDK-specific placeholders outside IMA. The discussion does not supply a complete authoritative replacement contract. Inferring a private field's meaning from its name or one observed URL would create a new uncertainty.

These are older evergreen questions, not evidence of a fresh SDK outage. This guide uses official references checked on 1 November 2026 to diagnose supported substitutions. It does not reverse-engineer undocumented IMA telemetry or prescribe a replacement SDK.

Related guide

Record the VAST substitution path.

Use the checklist to compare the template with the request made by the substituting system.

Use the tracking QA checklist

Opens a practical guide. No email required.

1. Establish which URI and substitution layer you mean#

A video delivery path can contain an initial ad request, wrapper requests, a media request and event-specific tracking requests. A value visible in one does not establish what another contained. Begin with one failing field in one named request.

The VAST 4.3 macro section assigns substitution responsibility to the party performing the HTTP request. That is often the player; an SSAI server can act instead. Record this owner before asking someone to edit a tag.

BoundaryEvidence to retainQuestion it answers
Trafficked templateVersion and original placeholder spellingWhat was configured?
VAST response or wrapperExact URI delivered to the next actorWhat did that actor receive?
Substitution actorPlayer, SDK, server or agreed vendor layerWho had the value and responsibility?
Emitted requestActual encoded URI, time and contextWhat was attempted?
ReceiverParsed field and campaign association, if exposedWhat was interpreted?

Add a request-local identifier only if your integration actually provides one. Preserve campaign and creative identifiers where available, without inventing a join between unrelated requests. Record wall-clock timezone for cross-system matching and elapsed time for local ordering.

For a mixed path, the SSAI ownership guide helps identify which system requests ads and fires each event. Avoid assigning every substitution to the browser simply because the content plays there.

2. Identify the macro's namespace and supported context#

Square brackets alone do not prove that a token is an IAB macro. A template may also contain ad-server macros, integration-specific variables or proprietary SDK fields. Give each token a documented owner and definition.

The current IAB macro registry data records each macro's meaning, context, type and support conditions. For example, ERRORCODE belongs to error tracking URIs. PAGEURL describes the top-level page and has context-dependent support and unavailable-value rules. Their appearance in one list does not make them interchangeable fields.

Google's Ad Manager macro reference uses its own syntax and case-sensitive names. It also distinguishes automatic insertion for recognized third-party tags from manual configuration in custom creatives and templates. Verify that the saved field is processed by the expected ad-server layer.

Likewise, consult the IMA platform compatibility reference for the actual integration. A broad “VAST supported” label does not prove support for every macro, optional feature or undocumented SDK-specific token. Ask the responsible vendor for the exact supported contract when its public references do not answer that field's behavior.

Write “definition or support unverified” in the worksheet when necessary. Guessing that an abbreviation means a Unix timestamp, advertising identifier or volume value is not a safe repair. Preserve the uncertainty and the original field instead of turning one historical example into an implementation rule.

3. Capture one authorized runtime attempt#

Use a supported test page, test inventory or another explicitly authorized diagnostic environment. Open the Network panel before the attempt. Narrow the capture to the relevant host or path, while retaining enough surrounding activity to identify wrappers and redirects.

Chrome's Network tutorial describes filtering, response inspection and request initiators. Inspect the relevant VAST response, then follow the outgoing request that contains the field. If the target event has not occurred, the absence of its request does not prove that macro replacement failed.

The Network reference documents Preserve log across page loads and the Payload tab's source and decoded views. Save which view you inspected. A UI showing [PAGEURL] might be displaying a decoded representation of percent-encoded brackets; that still does not establish a resolved page value.

Keep the raw encoded request separately from a readable diagnostic copy. Do not repeatedly decode the evidence until it resembles the value you expected. Each transformation should state which boundary requires it and what changed.

For SSAI or other server-owned calls, request the equivalent outbound trace from that owner. A missing browser request is not proof of a missing server request. If outbound or receiver logs are unavailable, mark the boundary unobserved rather than assigning it a successful status.

Do not replay impression, click or completion URLs to populate a report. Replaying can create additional attempts and obscure the original sequence. Reading a captured request and testing string transformations locally are different actions from sending it again.

4. Separate substitution failure from encoding failure#

A resolved value can still be encoded incorrectly. Conversely, a perfectly URL-encoded placeholder can remain unresolved. Check these independently.

VAST 4.3 specifies component encoding for replacement values. For array-valued macros, encode the individual values while retaining the comma separator. Its unavailable-value rules distinguish unknown from policy-withheld information and warn against applying a blanket replacement to arbitrary unknown tokens.

Use the current macro's own definition for applicability and special values. Do not fill a privacy-withheld field with a guessed identifier, copy an unrelated campaign's value or replace every unknown token with -1. Such a change can make a URL look tidy while misrepresenting the evidence.

Nested URLs need a boundary-specific contract. Google's custom-creative macro guide explains escaped, unescaped and double-escaped variants for its supported click workflows. That is not a universal rule that every VAST URL must be encoded twice. Count actual embedding and decoding boundaries instead of selecting the most escaped-looking form.

Worked encoding example: a value containing a URL#

This is a hypothetical string exercise. The hostname is illustrative; do not send requests to reproduce it. Suppose a receiver expects a query parameter named page containing this complete value:

https://example.invalid/watch?episode=7&mode=full

As one query-parameter value, component encoding produces:

https%3A%2F%2Fexample.invalid%2Fwatch%3Fepisode%3D7%26mode%3Dfull

The JavaScript component-encoding reference explains this operation. A local worksheet can compare the expected value with the encoded text without making a network call.

If the inner ampersand is emitted raw, a conventional outer query parser can interpret mode=full as a separate parameter. If the already encoded text is encoded again, %26 becomes %2526; one decoding step then leaves %26, rather than restoring the intended ampersand. Whether another encoding layer is required depends on a real additional embedding boundary.

Inspect three separate strings: the intended inner value, the emitted outer URI and the receiver's result after its documented parsing step. Also distinguish XML entity escaping from URI component encoding. A serialized XML representation and a URL parameter have different syntax; transforming both as though they were the same string can hide the actual defect.

5. Ask what the receiver actually used#

An HTTP success response shows that a request received a response at that boundary. It does not establish that the receiver associated every field with the intended campaign, accepted it as a reportable event or counted a viewable impression.

Where authorized receiver evidence exists, ask for the parsed value, validation result and relevant association. Compare these with the outbound representation from the same request. Keep “request observed,” “field parsed” and “event included in report” as separate checkpoints.

The missing-viewability diagnostic addresses whether the measurement event itself was supported and observable. Correcting a macro cannot manufacture a viewability observation that the integration never produced. The VAST error and timeout guide owns media and wrapper failures that require a different next step.

A hypothetical audit: preserve the unknown portion#

Imagine reviewing one required diagnostic field across 50 authorized test attempts. Classify each attempt once by the first demonstrated problem or its complete available path:

ClassificationAttempts
Emitted value and receiver-parsed value match the agreed contract32
Placeholder survives into the emitted request6
Value is substituted, but receiver parsing shows an encoding defect5
Outgoing request is visible; receiver evidence is unavailable4
No relevant outgoing request captured; ownership or capture remains unresolved3

These categories sum to 50. Observed complete-path agreement is 32 / 50, or 64%. Among the 43 attempts with enough evidence to reach the first three classifications, agreement is 32 / 43, approximately 74.4%.

The seven incomplete cases are not seven failed substitutions. They are an evidence queue. Neither percentage is an IVT rate, completion rate, paid-impression rate or estimate of website traffic. Define the selected field and test cohort before comparing a later audit; a different creative or substitution actor can change the population.

Repair one boundary, then retest the same contract#

A useful correction names the actor, supported field and demonstrated defect. Examples include fixing the documented macro spelling in the trafficked version, supplying an available permitted value at the responsible actor, or correcting one encoding boundary confirmed by receiver evidence.

Retest with a new authorized attempt and retain the earlier trace. Confirm that the deployed creative or template is the version you changed. Test the affected path and one relevant neighboring case, such as a permitted unknown value or a different wrapper route. Do not claim historical reports have been repaired because a new request is correct.

The anonymized streaming-publisher verification case concerns bounded measurement evidence, not universal access to player or server internals. For campaigns already measured through AdProof, request a scoped evidence review with the available campaign export, exact dates, timezone and relevant filters alongside the publisher's runtime trace. Keep unavailable substitution and receiver evidence explicit; an event export does not automatically expose every original VAST URL or private SDK field.

Frequently asked questions#

Can Chrome show a macro after replacement?

For a browser-owned request, inspect the actual Network entry and distinguish source from decoded parameter views. For a server-owned call, obtain server evidence. A template alone does not show the final runtime value.

Should every unknown macro become minus one?

No. Apply only the documented rules for that macro and context. Unknown, policy-withheld and inapplicable values can have different meanings. Arbitrary proprietary tokens do not acquire IAB semantics because they use brackets.

Does an encoded bracket mean replacement succeeded?

No. Encoding a placeholder changes its representation, not its meaning. Compare the template, emitted URI and receiver-parsed value to determine whether a real supported value was substituted.

Does HTTP success prove the event was counted?

No. Request response, field interpretation, report inclusion and the underlying measurement event require separate evidence. Preserve the unresolved boundary instead of treating HTTP success as a counting or viewability receipt.

Your next step

Record the VAST substitution path.

Use the checklist to compare the template with the request made by the substituting system.

Use the tracking QA checklist

Opens a practical guide. No email required.

Back to all field notes