VastMacroValueProvider

A callback used for dynamically providing values for VAST macros in URLs. This callback is invoked for each macro present in a URI before sending the HTTP request.

Macro names are considered case sensitive. The values provided by this function are URL encoded, before inserted in the respective URIs.

The VastMacro.values may already contain pre-filled values by the player. For both the VastMacro.values and the return list of this callback, an empty list is equivalent to no value for the macro and results in a default "unknown" macro replacement i.e. -1 in the URIs.

Any pre-filled values are best effort suggestions and can be modify, remove or overridden.

Example:

val vastMacroValueProvider = VastMacroValueProvider { macro, context ->
    when (macro.name) {
        // Setting or overriding values
        "CUSTOMMACRO" -> listOf("customValue")
        "PLAYHEADPOSITION" -> listOf("0.5")
        // Dynamic value based on context
        "CONTEXTAWARE" -> if (context.scope == VastMacroScope.TrackingPixel) listOf("pixel") else listOf("url")
        // Adding an additional value to the existing one
        "EXTEND" -> (macro.values ?: emptyList()) + "another value"
        // Unset the value
        "UNSET" -> emptyList()
        else -> macro.values
    }
}