TAP and TAP Programmatic return a VAST inline file. Note that TAP previously returned a VAST wrapper file, but that was discontinued as of 2022-07-14.
The actual content of each VAST file returned depends on the creative manager used, so you should ignore fields not mentioned here that your parser does not recognize or cannot handle.
For information about ad response with industry separation, see Industry Separation.
HTTP Response Codes
Code | Message | Description |
|---|---|---|
200 | OK | Success. Response may or may not contain an ad. |
400 | Bad Request | One of the required parameters is missing or has an invalid value (e.g., the placement ID does not exist). |
404 | Not Found | The endpoint being called is incorrect. |
Other standard HTTP errors, such as 500 Internal Server Error, or 405 Method Not Allowed, may also be returned. Applications should handle HTTP response codes according to standard conventions, as described in w3.org protocol RFC9110.
200 – Ad Response
The ad returned by the On-Demand Ad Service is VAST compliant. The client application should thus support the IAB's latest VAST Specification.
The VAST subset that must be supported by client applications is:
Audio In-Line Ads
Audio Content Types: MP3, AAC
Ad Title
Impression URLs (see Impression Reporting)
Media Files using progressive delivery (multiple files can be returned)
Tracking URLs for quartiles (see Quartiles)
Companion Banners
IFrameResource, HTMLResource, and StaticResource
Banner Content Types: JPG, PNG, GIF
Click Tracking URLs on Companion Banners (both Click-Through and Click-Tracking URLs)
Tracking Events: creativeView
Banner Alt Text
<Error> Element
The VAST response (when not a missed opportunity) includes an <Error> element with a URI to call if the ad returned is not played.
The <Error> element enables the media player to provide feedback to ad servers when an ad cannot be served. The VAST specification (section 2.3.6: Error Reporting) describes the error reporting in more detail. The VAST Error Codes Table to replace the [ERRORCODE] macro are described in section 2.3.6.3.
Triton Digital highly recommends you implement logic into your player to call the <Error> element when the ad is not played, because:
Providing more detailed error codes enables stronger diagnostics and enables better technology development over time.
Capping is triggered by the request, not by the impression. So if you are using capping and not calling the error URI when an ad is not played, the ad server considers the ad as having been served and therefore applies capping where it is not needed.
See URL Encoding Options for Error Element, below.
200 – No Ad Response (Missed Opportunity)
If the On-Demand Ad Service has no available ad that matches the request's parameters, it will still return a 200 OK response code and a VAST file, but with no <Ad> element. Instead, an optional <Error> element can be included in the file, such as:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VAST version=" 4.3">
<Error>
<![CDATA[https://adserver.com/?dur=%5BTD_DURATION%5D]]>
</Error>
</VAST>The <Error> element is optional, but if included, the player must send a request to the provided URI when and if an impression was generated (e.g., if filler content was played). This allows Triton Digital to record the filled duration of this missed opportunity in order to provide accurate forecasting.
If a
[TD_DURATION]macro is included in the URI, it should be substituted with the actual duration, in seconds, of the filled content. If the macro is not substituted, 30 seconds is assumed by default. For a given ad request, this URI can be called multiple times (the final duration that is logged is the sum of each individual call’s duration).If an
[ERRORCODE]macro is included in the URI, the player should substitute with the value 202.
URL Encoding Options for Error Element
There are two options for how you handle the <error> element described above, depending on whether or not you use macro substitution.
If not using macro substitution:
Call the CDATA as-is (in valid URL-encoded form) without performing macro substitution.
For example, you will receive: <![CDATA[http://adserver.com/?dur=%5BTD_DURATION%5D]]>
...and you should call: https://adserver.com/?dur=%5BTD_DURATION%5D
If using macro substitution:
URL decode the element, apply macro transformations, then URL encode before sending the request.
For example, you will receive: <![CDATA[http://adserver.com/?dur=%5BTD_DURATION%5D]]>
...which you decode to: https://adserver.com/?dur=[TD_DURATION]
...then replace [TD_DURATION] with the actual duration value (in this example, 20)
...and you should call: https://adserver.com/?dur=20