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 no replacement of the macro in the URIs. Consult the VAST specification for more information on values with special meaning.

Any pre-filled values are best effort suggestions and can be modified, removed 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
    }
}