# 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](https://docs-preview.optiview.dolby.com/pr-943/ads/workflows.md):

* **[VAST](https://docs-preview.optiview.dolby.com/pr-943/ads/workflows/live/vast.md):** the SDK appends them to the VAST tag URL as URL-encoded query parameters.
* **[Google Ad Manager](https://docs-preview.optiview.dolby.com/pr-943/ads/workflows/live/google-ad-manager.md):** they are sent to Google as ad tag parameters (`adTagParameters`). See Google's [list of all recognized ad tag parameters](https://support.google.com/admanager/answer/10678356#expand-all).
* **[Static assets](https://docs-preview.optiview.dolby.com/pr-943/ads/workflows/live/static-assets.md):** 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](https://docs-preview.optiview.dolby.com/pr-943/ads/concepts/breaks.md#scheduling) with a VAST or vendor asset, you can add an `assetParameters` map to the asset. For a VAST asset:

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

For a Google Pod Serving vendor asset:

```json
{
  "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](https://docs-preview.optiview.dolby.com/pr-943/ads/concepts/break-manifest.md), 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](https://docs-preview.optiview.dolby.com/pr-943/ads/integrations/google/pod-serving.md#required-google-parameters) 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](https://docs-preview.optiview.dolby.com/pr-943/ads/how-to-guides/asset-parameter-macros.md) 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](https://docs-preview.optiview.dolby.com/pr-943/ads/player-integration/optiview-ads-sdk.md) documentation for the full integration.

**Web**

```typescript
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**

```kotlin
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**

```swift
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**

```typescript
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](https://docs-preview.optiview.dolby.com/pr-943/ads/how-to-guides/asset-parameter-macros.md) | Device values in parameter values.              |
| [VAST](https://docs-preview.optiview.dolby.com/pr-943/ads/workflows/live/vast.md)                                    | Playing VAST tags with the SDK.                 |
| [Google Ad Manager](https://docs-preview.optiview.dolby.com/pr-943/ads/workflows/live/google-ad-manager.md)          | Playing Google pods with the SDK.               |
| [Google Pod Serving](https://docs-preview.optiview.dolby.com/pr-943/ads/integrations/google/pod-serving.md)          | Required Google parameters and pod decisioning. |
| [Breaks](https://docs-preview.optiview.dolby.com/pr-943/ads/concepts/breaks.md)                                      | Scheduling breaks with VAST and vendor assets.  |
| [OptiView Ads SDK](https://docs-preview.optiview.dolby.com/pr-943/ads/player-integration/optiview-ads-sdk.md)        | Integrating the SDK with your player.           |