This section describes the query string parameters that are used to enable On-Demand advertising on Triton Digital services. These parameters are to be sent in addition to the parameters described in Parameters, in the Advertising Technical Specification.
You should only send a parameter if you specifically want to pass a value for that parameter. If you do not want to pass a value, you should not send the parameter.
Parameters can be provided either in the query string of the endpoint URI, or, when indicated, as an HTTP header field. When both are received, the query string is evaluated first, and the HTTP Header is evaluated second, in the order presented in this page.
Note that query string parameters supporting a list can be set as raw comma-separated, or as URL encoded.
Query String | HTTP Header | Description | Format |
|---|---|---|---|
stid | ID of the placement (historically known as the "station ID"). This parameter is required. See STID Note below, for alternatives. | Integer value. | |
type | Ad position. This parameter is required, | String. Valid values:
| |
maxAds | When the parameter value is greater than 1, the on-demand ad server returns an ad pod containing a number of ads up to the parameter value, and the sequence attribute is used in the response. When the ad server has only one ad element to return, an ad pod is not used, and the sequence attribute is not used in the response. (See Ad Pod Usage Notes below for more information about ad pods, and Break Positioning Usage Notes below for how maxAds can affect "last in break" targeting.) This parameter is optional; if not provided, the value assumed is 1. | Integer. Valid values between 1 and 10. | |
ip | X-Device-IP | IP address of the player/listener device. This parameter is required for server-to-server integrations. | For IPv4: Dotted decimal format (e.g., For IPv6: Colon-separated hexidecimal characters conforming to IPv6 standard (e.g., |
ua | X-Device-User-Agent | User-Agent HTTP header of the player/listener device. This parameter is required for server-to-server integrations. | URL-encoded if sent as a query string. |
referrer | X-Device-Referer | Referrer HTTP header of the player/listener device (URL of the page the player is embedded in). This parameter is recommended for browser-based players in server-to-server integrations. Note: the spelling of X-Device-Referer is correct for this usage (one "r"); the "HTTP referer" has used that unfortunate spelling since the beginning of the protocol. It is unclear whether Phillip Hallam-Baker or Tim Berners-Lee is to blame. (Hallam-Baker blames Berners-Lee.) | URL-encoded if sent as a query string. |
device-language | X-Device-Accept-Language or | HTTP header of the player/listener device. This indicates which languages the client is configured for, and which locale variant is preferred. We do support both: query string and/or HTTP Header. This parameter is recommended for server-to-server integrations. | String. Two-letter code that corresponds to ISO-639-1 language codes. |
device-os | Device operating system (e.g. iOS). | String. | |
device-osv | Device operating system version (e.g. 3.1.2) | String. | |
mindur | Minimum duration in seconds allowed for the requested ad. If using this parameter, it will override TAP Programmatic media duration that is set in Prog. Ad Quality. For information about how this parameter works with maxAds and ad pods, see Ad Pod Usage Notes. | Integer. | |
maxdur | Maximum duration in seconds allowed for the requested ad. If using this parameter, it will override TAP Programmatic media duration that is set in Prog. Ad Quality. For information about how this parameter works with maxAds and ad pods, see Ad Pod Usage Notes | Integer. | |
iab-categories-to-exclude | List of ad categories NOT allowed for the requested ad. The categories are defined in the IAB DAAST specification and listed with codes in OpenRTB. (Although the DAAST specification is obsolete, its ad categories are still in regular use. Triton will update to the IAB Ad Product Taxonomy once it has reached an acceptable level of use.) Note: blocking a tier-1 category does not block tier-2 under it (e.g., blocking IAB1 does not block IAB1-1 to IAB1-7). To block a category's tier-2, each tier-2 category should be blocked individually. | Comma-separated list of codes (strings). | |
feed-type | Required for the specific use-case where the inventory is offered to programmatic and ads requested through on-demand are stitched into a podcast. Can also be used for live stream (See also: delivery-method.) | String. Valid values:
| |
content-language | The language of the content where ads will be played. This can be used in campaign targeting or to define a specific rule on the ad exchange. | String. Two-letter code that corresponds to ISO 639-1 language codes. | |
iab-v2-cat | Category of the content as defined by the IAB Tech Lab Content Taxonomy V2 (XLXS file). The first category in the list will be considered as the main category. This parameter is recommended for personalized audio content (e.g., music services) where genre is dynamic and based on listener's choice. See IAB Category Usage Notes. | Comma-separated list of integer values, each in the 1-698 range. (See IAB Category Usage Notes, below.) | |
site-url | URL of the website where the ad will be heard. This is used by programmatic buyers to identify the inventory they bid on. It is also used to verify if Triton Digital is allowed to sell your inventory using the ads.txt framework. If not sent, Triton Digital will use the value configured for this placement. For more information, see Authorized Digital Sellers (ads.txt). | URL encoded string of a URL, which must include the protocol (e.g., http or https). Example:
| |
delivery-method | How the audio content will be delivered to the listener. This parameter is required if the content in which the ad will appear is downloaded, and ad inventory is offered to programmatic buyers. | String. Valid values:
| |
break-id | Break-ID | Universally unique identifier (UUID) used to identify on-demand ad breaks for industry separation. Must be unique per listener. For more information, see Industry Separation. | String |
break-context | Break-Context | Encoded string returned from Triton Digital in response to a break-id; the break context string should be sent back to Triton Digital with the next ad request. For more information, see Industry Separation. | String |
break-position | Force break positioning of the requested ads to match corresponding content targeting. In the case of multiple ads delivered, only one ad (either first or last) is expected to match that targeting. The parameter is optional. For more information, see Break Positioning Usage Notes, below. | String. Valid values:
| |
break-number | The break number within the podcast episode. | Integer | |
series-title | Series title (podcast content). | String. | |
episode-season | Season number (podcast content). | String. | |
episode-number | Episode number (podcast content). | String. | |
episode-title | Episode title (podcast content). | String. | |
episode-url | Episode origin URL (podcast content). | URL-encoded if sent as a query string. | |
episode-duration | Episode duration. | Integer. | |
guid | Episode ID. | Integer. |
The placement ID (stid) is the preferred method to indicate for which placement the On-Demand ad request is being made, but Triton Digital also supports alternative methods such as the station name or an external ID. Please contact your Triton Digital Solutions Specialist if you want to learn more about this.
Delivery Method Notes
Below are the definitions of the delivery-method values.
Streaming: for endless flow of content, such as live radio. The user session ends only when the device closes the connection. The content is retrieved as it is consumed. This also applies to on-demand music services (although not "live" on-demand performances because new content is constantly added to the playlist as current content is consumed.
Download: for pre-recorded/finite single content, such as a podcast. The user session ends once the content is downloaded (or before, if the user disconnects midway). Typically, content retrieval and consumption are independent, such as when a listener downloads a podcast then listens to it later, possibly even when the device is offline. Thus, the impressions are triggered by the download, not the consumption.
Progressive: or “progressive download”, is for the same type of pre-recorded/finite content as download, but the content is retrieved as it is consumed. This must be enforced by the player on the user device. It is a client implementation, so server-side implementations that throttle the download rate (e.g., based on content bitrate) do not qualify a session as progressive download.
Ad Pod Usage Notes
An ad pod is a group of multiple ads contained in a single response. Multiple <Ad> elements are provided with <sequence> attributes; the result is a VAST with multiple ads ordered with sequence numbers (first ad selected is "1," etc.). Ads are selected based on their priority/weight.
An ad pod can contain multiple ads from direct sources but only one programmatic ad. Note that if you use mindur and/or maxdur along with maxAds (with a maxAds value greater than "1") the specified minimum/maximum durations apply to each ad in the ad pod, not the total duration of the ad pod. When a request includes a break-id and a maxAds parameter, the break context that is returned contains all of the IAB categories and advertiser IDs contained in the ad pod.
There is capping logic embedded in an ad pod; an ad pod will not contain two or more ads from the same TAP flight, nor will it contain two or more ads using the same IAB category. Note that you can apply Industry Separation within ad pods.
IAB Category Usage Notes
All of the following parameters must be included in the ad request in order to use IAB v2 and thus make an IAB v2 impression for podcast:
guidbreak-numberbreak-idipua
If any of the above parameters are not included, IAB v1 is used.
IAB values greater than 698 are accepted, but will be ignored. E.g., if we receive iab-v2-cat=1068 (1068 = English) this won't set the content language to English. Instead, use the dedicated content-language parameter.
Unlike broadcast content where the program's genre is static, the content category (iab-v2-cat) of personalized music services is dynamic and depends on listener selection. In order to take advantage of advertising campaigns that target listeners by content preference, use the iab-v2-cat parameter in your ad requests. Configure your player to use the iab-v2-cat value that most closely matches the listener's current content category selection. This alerts higher-value targeted campaigns to the available targetable inventory.
Break Positioning Usage Notes
Usage of break-position is closely related to targeting position-in-break. If you do not use this kind of targeting, simply ignore this parameter.
When passing a break-id and break-context, first position is automatically determined by the ad server. If you don’t use break-context, you must use break-position=first so that the first flight delivered targets the first position, if possible.
Last position on the break cannot be determined by the ad server. Even when using break-context, you must use break-position=last to indicate that this will be the last ad request concerning that particular break, so that the last flight delivered targets the last position, if possible.
Even if maxAds is above 1, only one returned ad will target either the first or last position. Also, the number of ads returned must match the number of ads requested before the last one can be considered last position. If the ad server returns fewer ads than requested, none of them will target last position. For example: if maxAds is 3 and only the first position is filled, the "last in break" ad will not be delivered.