Skip to main content
Version: v2

Asset parameter macros

A break is defined once in the backend, but some targeting values are only known on the viewer's device: the size of the player, the length of the ad slot, the viewer's team, or a consent string. Macros bridge that gap. A macro is a placeholder token inside an asset parameter value. The OptiView Ads SDK replaces it with the actual value on the device, at the moment it builds the ad request.

How macros work​

A macro is a token of the form $NAME$: a $, a name made of letters, digits, and underscores, and a closing $. Put one or more tokens anywhere in a parameter value, on the break, in the session configuration, or in an updateAssetParameters() call:

{
  "type": "vast",
  "mediaType": "video",
  "uri": "https://adserver.example.com/vast?slot=midroll",
  "assetParameters": {
    "size": "$OPTIVIEW_PLAYER_WIDTH$x$OPTIVIEW_PLAYER_HEIGHT$",
    "team": "$TEAM$"
  }
}

When the SDK requests this VAST tag on a 1920×1080 player, for a viewer whose app registered $TEAM$ as ajax, the request becomes:

https://adserver.example.com/vast?slot=midroll&size=1920x1080&team=ajax

The rules:

  • Resolved per ad request. The SDK fills in the macros every time it builds an ad request, so a value that changes during the session, such as the player size, is always current.
  • Whole tokens only. Matching is case-sensitive and uses the full token: $APP$ never matches inside $APP_NAME$.
  • Several tokens per value. A value can combine text and any number of tokens, as size does above.
  • A lone $ is left alone. A $ without a closing $, and forms such as $$ or ${NAME}, are not macros and are sent unchanged.

Where macros apply​

The SDK resolves macros in every asset parameter it sends, for every ad source:

Ad sourceWhere the resolved parameters go
Static assetsAppended as query parameters to the URL the SDK requests: the asset's uri, a static companion, or a pause ad. For HLS and DASH, only the master playlist or MPD request carries them.
VASTAppended as query parameters to the VAST tag URL.
Google Ad ManagerSent to Google as ad tag parameters (adTagParameters).
Signed static asset URLs

Do not use asset parameters on a static asset with a signed URL or a URL that carries an access token. The added query parameters can invalidate the signature. Parameters set in the SDK are added to every static asset request in the session.

Built-in macros​

The SDK provides these macros on every platform, unless noted:

MacroValue
$OPTIVIEW_PLAYER_WIDTH$Width of the ad container, in logical pixels.
$OPTIVIEW_PLAYER_HEIGHT$Height of the ad container, in logical pixels.
$OPTIVIEW_BREAK_DURATION_SECONDS$Duration of the ad, in seconds: the asset's duration, otherwise the break's.
$OPTIVIEW_BREAK_DURATION_MS$The same duration, in whole milliseconds.
$OPTIVIEW_USER_AGENT$The user agent of the device. Not available on iOS and tvOS: register your own value.

The names are also exported by the SDK, so you do not have to type them: OPTIVIEW_ASSET_PARAMETER_MACROS on Web and React Native, OptiViewAssetParameterMacros on Android, iOS, and tvOS.

Register your own macros​

Register your own macros with assetParameterMacros in the session configuration. Each macro is keyed by its full token, including both $ signs, and its value is either fixed or a callback. The SDK calls a callback each time it builds an ad request, so it can return the current value.

To override a built-in macro, register the same name: your value wins.

await sdk.startSession({
  manifestUrl: 'https://us.markers.optiview.dolby.com/manifest/v1/ORG-ID/channels/CHANNEL-ID',
  assetParameterMacros: {
    $SEGMENT$: 'sports',
    $TEAM$: () => currentTeam(),
  },
});

Registered macros are cleared when the session ends.

Update macros during a session​

Call updateAssetParameterMacros() to change macros while the session runs, for example when the viewer switches teams. The call merges the given names into the session's macros; names you leave out keep their current value. The new values apply to the next ad request: an ad that has already been requested is not requested again.

sdk.updateAssetParameterMacros({ $TEAM$: 'psv' });

To remove a macro you registered, pass undefined for it on Web and React Native, or null on Android and nil on iOS. A built-in macro with the same name then applies again.

Leave out a parameter with an empty macro​

Sometimes a parameter must not be sent at all, for example a consent string before the viewer has given consent. Mark the macro empty, and the SDK leaves out every parameter that uses it:

await sdk.startSession({
  manifestUrl: 'https://us.markers.optiview.dolby.com/manifest/v1/ORG-ID/channels/CHANNEL-ID',
  assetParameterMacros: {
    $CONSENT$: () => (hasConsent() ? consentString() : null),
  },
});

On Web and React Native, null marks a macro empty.

What is left out depends on the value:

Parameter valueWhat the SDK leaves out
A plain value, such as "gdpr_consent": "$CONSENT$"The whole parameter.
Google Ad Manager cust_params, such as "genre=sports&consent=$CONSENT$"Only the &-separated pair with the empty macro: cust_params=genre=sports is still sent. If no pair is left, the whole parameter.
A static asset value with &-separated pairsOnly the pairs with the empty macro, as for cust_params.

For VAST, every value counts as a plain value, also one with &-separated pairs: the whole parameter is left out.

Tokens the SDK cannot fill in​

A token without a value is never removed: the SDK sends the parameter with the token as it is.

  • Your ad server's own macros. A token that is neither built in nor registered, such as $PUBLISHER_ID$, is sent unchanged. Your ad server can then expand it on its side.
  • A built-in macro without a value, such as $OPTIVIEW_USER_AGENT$ on iOS, an unknown $OPTIVIEW_* name, or a registered macro whose callback returns no value, is also sent unchanged. The SDK reports it with the DA-ASSET-MACRO-UNKNOWN diagnostic, so you can spot a missing value during development.
ResourceDescription
Ad targeting parametersWhere asset parameters are set, and how the layers are merged.
Static assets on livePlaying creatives from your CDN.
Your ad server (VAST) on livePlaying VAST tags with the SDK.
Google Ad Manager on livePlaying Google pods with the SDK.