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.
The placement ID (stid) is the preferred method to indicate for which placement the On-Demand ad request is being made. Triton Digital also supports alternative methods such as the station name or an external ID. To learn more, see Contact Support.
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.
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"). Required. For alternatives, see STID Note. | Integer | |
type | Ad position. 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. This parameter is optional, the default is 1. 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. Also see Ad Pod Usage Notes and Break Positioning Usage Notes. | Integer. Valid values: 1 to 10. | |
ip | X-Device-IP | IP address of the player or listener device. Required for server-to-server integrations. | For IPv4: Dotted decimal format. Example: For IPv6: Colon-separated hexadecimal characters. Example: |
ua | X-Device-User-Agent | User-Agent HTTP header of the player/listener device. 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). Recommended for browser-based players in server-to-server integrations. Note: the use of one “r”in this spelling of X-Device-Referer is correct. | 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 or HTTP Header. Recommended for server-to-server integrations. | String. Two-letter code that corresponds to ISO-639-1 language codes. |
device-os | Device operating system. | String. Example: iOS | |
device-osv | Device operating system version | String. Example: 3.1.2. | |
mindur | Minimum duration in seconds allowed for the requested ad. If using this parameter, it overrides 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 overrides 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. To exclude a category's tier-2, each tier-2 category must be excluded individually. Excluding a tier-1 category does not block the tier-2 categories under it. For example, excluding only IAB1 does not block IAB1-1 to IAB1-7. 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. | String. Comma-separated list of codes. | |
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. Also see 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 is considered the main category. This parameter is recommended for personalized audio content, such as 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, 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 in the podcast episode. | Integer. | |
series-title | Series title for podcast content. | String. | |
episode-season | Season number for podcast content. | String. | |
episode-number | Episode number for podcast content. | String. | |
episode-title | Episode title for podcast content. | String. | |
episode-url | Episode origin URL for podcast content. | URL-encoded if sent as a query string. | |
episode-duration | Episode duration. | Integer. | |
guid | Episode ID. | String. In standard UUID format. |
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. It does not apply to "live" on-demand performances because new content is constantly added to the playlist as current content is consumed.
download: for pre-recorded or 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: For the same type of pre-recorded or 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 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 request with multiple ads ordered with sequence numbers. 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 or maxdur along with a maxAds value greater than "1", the specified minimum and 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. Instead, use the dedicated content-language parameter. For example, if Triton receives iab-v2-cat=1068 (1068 = English), this won't set the content language to English.
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. 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.