Ad targeting parameters

When an ad server decides which ad fills a break, you can pass key-value parameters with the ad request to personalize the ads — for example the content genre, the placement type, or custom targeting values. In OptiView Ads, these parameters are called assetParameters. How they reach the ad server depends on the ad workflow:

• VAST: the SDK appends them to the VAST tag URL as URL-encoded query parameters.
• Google Ad Manager: they are sent to Google as ad tag parameters (adTagParameters). See Google's list of all recognized ad tag parameters.
• Static assets: the SDK appends them as query parameters to the URL of the creative it requests.

You can set assetParameters in two places: on the break in the backend, and in the OptiView Ads SDK on the client.

Asset parameters in the backend

When you schedule a break with a VAST or vendor asset, you can add an assetParameters map to the asset. For a VAST asset:

{
  "type": "vast",
  "mediaType": "video",
  "uri": "https://adserver.example.com/vast?slot=midroll",
  "assetParameters": {
    "content_genre": "sports"
  }
}

For a Google Pod Serving vendor asset:

{
  "type": "vendor",
  "vendor": "gam",
  "vendorParameters": {
    "type": "pod"
  },
  "assetParameters": {
    "description_url": "https://www.example.com/sports/live.html",
    "cust_params": "genre=sports"
  }
}

OptiView Ads delivers these parameters to the player through the Break Manifest, so they are included on the ad request. For Google, they are also forwarded to Google when the break is announced; see Google Pod Serving for the parameters Google requires.

Asset parameters in the OptiView Ads SDK

The OptiView Ads SDK can add its own assetParameters. There are two client-side layers:

• Session parameters — passed to startSession(), they apply to every break in the session.
• Live updates — passed to updateAssetParameters() during an active session, for values that change while the viewer is watching.

How the layers are merged

The layers are merged per key, from lowest to highest precedence:

1. The session's assetParameters from startSession().
2. The latest updateAssetParameters() call.
3. The break's assetParameters from the backend.

A value set on the break wins over the same key set in the SDK, so set each key in one place only. Overwriting one key never discards the others, and live updates apply to future breaks only: a break whose ad request has already been sent cannot be retargeted.

Backend or client?

As a rule of thumb:

• Set through the backend the values that describe the break or the content and are the same for every viewer — such as description_url, the placement declaration, and campaign or content targeting that is known when the break is scheduled.
• Set through the SDK the values that depend on the viewer, the device, or the moment of playback — such as device identifiers, consent state, autoplay/mute state (vpa, vpmute), or audience context that changes during the session.

Macros

A parameter value can contain macros: $NAME$ tokens that the SDK replaces with a value from the device when it builds the ad request. For example, "size": "$OPTIVIEW_PLAYER_WIDTH$x$OPTIVIEW_PLAYER_HEIGHT$" is sent as size=1920x1080. The SDK has built-in macros for the player size, the ad duration, and the user agent, and your app can register its own.

See Asset parameter macros for how macros work, the built-in macros, registering and updating your own, and leaving out a parameter with an empty macro.

Platform examples

The examples below start a session with session-level assetParameters and update them mid-session. See the OptiView Ads SDK documentation for the full integration.

Web

await sdk.startSession({
  manifestUrl: 'https://us.markers.optiview.dolby.com/manifest/v1/ORG-ID/channels/CHANNEL-ID',
  assetParameters: { cust_params: 'genre=sports' },
});

// Update targeting mid-session — applies to future breaks, no restart needed
sdk.updateAssetParameters({ cust_params: 'sport=basketball' });

Android

sdk.startSession(
    SessionConfig(
        manifestUrl = "https://us.markers.optiview.dolby.com/manifest/v1/ORG-ID/channels/CHANNEL-ID",
        assetParameters = mapOf("cust_params" to "genre=sports"),
    )
)

// Update targeting mid-session — applies to future breaks, no restart needed
sdk.updateAssetParameters(mapOf("cust_params" to "sport=basketball"))

iOS

try await sdk.startSession(
    SessionConfig(
        manifestUrl: "https://us.markers.optiview.dolby.com/manifest/v1/ORG-ID/channels/CHANNEL-ID",
        assetParameters: ["cust_params": "genre=sports"]
    )
)

// Update targeting mid-session — applies to future breaks, no restart needed
sdk.updateAssetParameters(["cust_params": "sport=basketball"])

React Native

await ads.startSession({
  manifestUrl: 'https://us.markers.optiview.dolby.com/manifest/v1/ORG-ID/channels/CHANNEL-ID',
  assetParameters: { cust_params: 'genre=sports' },
});

// Update targeting mid-session — applies to future breaks, no restart needed
ads.updateAssetParameters({ cust_params: 'sport=basketball' });

Related resources

Resource	Description
Asset parameter macros	Device values in parameter values.
VAST	Playing VAST tags with the SDK.
Google Ad Manager	Playing Google pods with the SDK.
Google Pod Serving	Required Google parameters and pod decisioning.
Breaks	Scheduling breaks with VAST and vendor assets.
OptiView Ads SDK	Integrating the SDK with your player.