Ad Request Parameters
Pass viewer-specific and device-specific ad request parameters, such as consent, page URL, device ID, and targeting, from your host app to VAST ads with adTagParams.
Overview
For VAST ads, your host app supplies the ad request parameters that depend on the viewer or the
device: consent, page or app identity, device ID, user ID, and targeting. Your player passes them to
the SDK through adTagParams, and the SDK adds them to the ad request.
Parameters that are the same for every viewer, such as the ad unit path and sizes, stay in
StreamLayer Studio, in the Video Tag of the ad unit.
Usage
Pass adTagParams to StreamLayerProvider. Update the prop whenever a value changes, for example
when your consent management platform answers. The provider keeps the running SDK in sync.
import { useMemo } from 'react'
import { StreamLayerProvider, type AdTagParams } from '@streamlayer/react'
import { StreamLayerSDKAdvertisement } from '@streamlayer/react/advertisement'
import '@streamlayer/react/style.css'
type PlayerProps = {
tcString?: string
userId: string
}
export const Player = ({ tcString, userId }: PlayerProps) => {
const adTagParams = useMemo<AdTagParams>(
() => ({
// Common parameters, sent to every ad server
gdpr: 1,
gdpr_consent: tcString,
// Google Ad Manager parameters, sent only to Google Ad Manager tags
gam: {
url: window.location.href,
description_url: window.location.href,
npa: '1',
ppid: userId,
cust_params: { sport: 'football', lang: 'en' },
},
// Any other ad server, keyed by the tag host
custom: {
'ads.example.com': { clickurl: 'https://track.example.com/c?u=' },
},
}),
[tcString, userId]
)
return (
<StreamLayerProvider
sdkKey="your-sdk-api-key"
event="your-event-id"
containerId="SL-Ad-Container"
adTagParams={adTagParams}
>
<div id="SL-Ad-Container">
<video />
<StreamLayerSDKAdvertisement sidebar="left" />
<StreamLayerSDKAdvertisement />
</div>
</StreamLayerProvider>
)
}Keys are the parameter names the ad server expects. The SDK sends them as given.
To set the values from code inside the provider, call setAdTagParams on the SDK instance. It
replaces the whole object, so pass every block each time:
import { useEffect } from 'react'
import { useStreamLayer } from '@streamlayer/react'
export const ConsentSync = ({ tcString }: { tcString?: string }) => {
const sdk = useStreamLayer()
useEffect(() => {
sdk?.setAdTagParams({ gdpr: 1, gdpr_consent: tcString })
}, [sdk, tcString])
return null
}Common Parameters
IAB privacy signals. They mean the same for every ad server, so you pass them once, at the top
level.
| Parameter | Value |
|---|---|
gdpr | 1 or 0: whether GDPR applies (IAB Transparency and Consent Framework) |
gdpr_consent | TCF v2 consent string |
us_privacy | IAB US Privacy string |
gpp, gpp_sid | IAB Global Privacy Platform string and section IDs |
Google Ad Manager Parameters
The gam block is applied to Google Ad Manager tags (*.doubleclick.net/gampad/ads). It accepts
any parameter that StreamLayer Studio shows under Advanced settings of a Video Tag. A key that
is not one of them is not sent, and the SDK logs a warning in the console. The ones a host app
usually passes:
| Group | Parameters |
|---|---|
| Page / app | url: URL the request is sent from; description_url: URL describing the video content; msid: app ID; an: app name; hl: request language |
| Device | rdid: resettable device ID; idtype: ID type; is_lat: Limit Ad Tracking; dth: device type hint |
| Privacy | gdpr, gdpr_consent, addtl_consent; npa: non-personalized ads; rdp: restrict data processing; ltd: limited ads; tfcd: child-directed; ppt: publisher privacy treatment |
| User | ppid: publisher-provided ID; cust_params: key-value targeting; ppsj: publisher-provided signals (Base64 JSON); pvid, pvid_s: app set ID and its scope |
| Player | vpa: autoplay; vpmute: muted; plcmt: placement type; vconp, aconp: continuous play; vpos: position; omid_p, sdk_apis |
| Session | correlator; sid: session ID |
Values are strings. cust_params also accepts an object, see Key-Value Targeting.
rdid, idtype, is_lat, msid, and an are for CTV and mobile apps. A browser has no
advertising device ID.
For the full list and a description of each parameter, see Google's
All VAST ad tag parameters.
Example for a CTV app:
import type { AdTagParams } from '@streamlayer/react'
export const buildAdTagParams = (advertisingId: string, limitAdTracking: boolean): AdTagParams => ({
gam: {
url: 'com.example.tvapp',
msid: 'com.example.tvapp',
an: 'Example TV',
rdid: advertisingId,
idtype: 'lgudid',
is_lat: limitAdTracking ? '1' : '0',
},
})Key-Value Targeting (cust_params)
cust_params)Pass key-values as an object. Pass several values of one key as an array. The SDK sends them as one URL-encoded cust_params parameter.
custParamsMode controls what happens to the key-values already configured in the Video Tag in StreamLayer Studio:
custParamsMode | Result |
|---|---|
'replace' (default) | Your key-values replace the ones configured in StreamLayer Studio |
'merge' | Your key-values are added to the ones configured in StreamLayer Studio. A key in both takes your value |
import type { AdTagParams } from '@streamlayer/react'
export const adTagParams: AdTagParams = {
custParamsMode: 'merge',
gam: { cust_params: { user: 'premium', team: ['home', 'away'] } },
}Other Ad Servers
Use the custom block for any other ad server. The key is the exact host of the ad tag; subdomains
are not included. The parameters are sent as given, and only to a tag on that host.
import type { AdTagParams } from '@streamlayer/react'
export const adTagParams: AdTagParams = {
custom: {
'ads.example.com': { clickurl: 'https://track.example.com/c?u=' },
},
}How Values Are Applied
- Query parameter and macro: Each key sets the query parameter of that name. If the Video Tag in StreamLayer Studio contains a macro of the same name (
[NAME],${NAME}or{NAME}), the key fills it too. - Values are sent as given: The SDK URL-encodes each value once and does not change it. A value that looks like a macro, such as
[timestamp], is sent as that text. - Empty values: An empty string or
undefinedcounts as not passed. It never clears a value configured in StreamLayer Studio. - Precedence: A value from your host app replaces the value configured in the Video Tag in StreamLayer Studio. Without a host value, the Studio value is kept. A key in
gamorcustomtakes precedence over the same key in the common block for that ad server. - Timing: The SDK reads the values when it requests an ad. A change applies to the next ad request.
- Prebid: For a Prebid auction link, the common parameters are sent in the auction request body (
regs.ext.gdpr,user.ext.consent,regs.ext.us_privacy,regs.gpp,regs.gpp_sid), and acustomentry for the auction host is added to the auction URL. - No
adTagParams: Ad requests are sent exactly as configured in StreamLayer Studio.
Macro Parameters
gdprApplies, tcString, and clickUrl fill macros in the ad tag.
| Parameter | Fills | Preferred alternative |
|---|---|---|
gdprApplies: boolean | ${GDPR} | gdpr: 1 or gdpr: 0 |
tcString: string | ${GDPR_CONSENT}, ${GDPR_CONSENT_<vendor ID>} | gdpr_consent |
clickUrl: string | [clickurl], [clickmacro], ${CLICKURL} | clickurl in the custom block of the ad server |
A macro parameter reaches the ad request only when the Video Tag in StreamLayer Studio contains its macro. Prefer gdpr and gdpr_consent from Common Parameters: they do not need a macro in the tag. When you pass both, gdpr and gdpr_consent are used.
import { StreamLayerProvider, type AdTagParams } from '@streamlayer/react'
const adTagParams: AdTagParams = { gdprApplies: true, tcString: 'your-tcf-consent-string' }
export const App = () => (
<StreamLayerProvider sdkKey="your-sdk-api-key" event="your-event-id" adTagParams={adTagParams}>
<video />
</StreamLayerProvider>
)Related
- Advertising — Render ad units with
StreamLayerSDKAdvertisement - External VAST Ads — Render your own VAST tag with
externalAdData - Exposed Pause Ad — VAST-compliant pause ad integration
- Integration Guide — Full Web SDK setup and configuration
Updated 4 days ago
