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.

ParameterValue
gdpr1 or 0: whether GDPR applies (IAB Transparency and Consent Framework)
gdpr_consentTCF v2 consent string
us_privacyIAB US Privacy string
gpp, gpp_sidIAB 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:

GroupParameters
Page / appurl: URL the request is sent from; description_url: URL describing the video content; msid: app ID; an: app name; hl: request language
Devicerdid: resettable device ID; idtype: ID type; is_lat: Limit Ad Tracking; dth: device type hint
Privacygdpr, gdpr_consent, addtl_consent; npa: non-personalized ads; rdp: restrict data processing; ltd: limited ads; tfcd: child-directed; ppt: publisher privacy treatment
Userppid: publisher-provided ID; cust_params: key-value targeting; ppsj: publisher-provided signals (Base64 JSON); pvid, pvid_s: app set ID and its scope
Playervpa: autoplay; vpmute: muted; plcmt: placement type; vconp, aconp: continuous play; vpos: position; omid_p, sdk_apis
Sessioncorrelator; 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)

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:

custParamsModeResult
'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 undefined counts 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 gam or custom takes 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 a custom entry 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.

ParameterFillsPreferred 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