When defining an Ad Server Source in broadpeak.io, you configure the ad tag URL which will allow the system to call the Ad Server.

The Ad Tag URL usually contains what is often called ad macros, placeholders that broadpeak.io will replace with actual values when requesting an ad response from the ad server. Those values will be used by the ad server to best target the ads to the playback context.

The actual ad tag and the necessary macros will be provided by the Ad Technology partner that acts as your Ad Server or SSP.

Macro Value Extraction and Mapping

When you configure your Ad Server Source, you need to tell broadpeak.io how to replace the ad macros with actual values, whether statically defined, or dynamically extracted from the playback context.

In the Web App

The simplest way to go about it is to use the broadpeak.io Web App. A form allows you to simply define all the query parameters added to the ad tag URL, and remap any placeholder (or existing value) with a dynamic value.

The various mapping types available are:

• Custom: is usually used for static (hard-coded) query parameters in the ad tag. Whenever that ad tag is called, that query will always have the same value.
• Forward: these parameters are retrieved from the query parameters present on the client request arriving to broadpeak.io, and forwarded without modification to the ad server.
• From Query Parameters: The value of those parameters is retrieved from the query parameters present on the client request. But - unlike with the forward type, the query parameter name can be different between the client request and the ad server call. So it's primarily used for remapping parameters.

  ⚠️

  Note that broadpeak.io is not case-sensitive when it comes to referring to incoming query parameters. Therefore deviceid is equivalent to deviceId and will extract values equally from deviceid and deviceId. In addition, if the query parameter contains a hyphen, it should be converted to underscore when added as value, eg. device_id if the call from the player contains device-id

• From Headers: the value of these query parameters is retrieved from a header in the client request. For example, it's quite typical to send the user agent to the ad server (even though broadpeak.io also forwards it as header).
• From Variable: the value of these query parameters is dynamically generated or calculated by broadpeak.io, from system data, or information obtained from the client request itself, or the source manifest.

Here is an example illustrating the various types of replacements:

With that configuration, a incoming request for the DAI service would be handled in the following way:

Client request to broadpeak.io...

stream.broadpeak.io/67432684324637642/default/index.mpd?content_genre=sport&device_id=123456

• from the IP 91.175.141.118
• with the header User-Agent: iOS
• and for an ad break announced in the stream with a duration of 119 seconds

... leads to broadpeak.io calling the ad server with the following URL

ad.server.com?app_bundle=588207&content_genre=sport&did=123456&ip=91.175.141.118&break_duration=119&ua=iOS

• the app_bundle param is configured as a static value
• the content_genre param is forwarded without modification
• the incoming device_id is remapped to the ad server parameter did
• the ip param is dynamically filled with the client's IP extracted from the request
• the break_duration is extracted from the source manifest (typically from the SCTE35 marker) for that specific ad break (in a Live Ad Replacement scenario)
• the ua param is filled with the client's User Agent, extracted from the incoming HTTP headers

💡

Note how you can paste an ad tag URL in the form (such as you would have obtained from your Ad Technology partner), and then simply go about remapping every query parameter one by one.
As you make changes, the URL is modified accordingly with broadpeak.io-specific placeholder. This allows you to easily copy it, ready for use in configuring another Ad Server Source, to document it, or even to provide it to our support team when asking for help.

With the APIs

You can create or modify an Ad Server source through the APIs as well. Unlike with the Web App, this method requires you to separate the base URL (protocol, domain name and path), and define the list of query parameters with the appropriate mapping.

The previous example done through the APIs would require sending the following payload to the "create ad server source" endpoint

{
   "name": "Ad server 1",
   "url": "https://ad.server.com/vast/",
   "template": "custom",
   "queryParameters": [
      {
         "name": "app_bundle",
         "type": "custom",
         "value": "588207"
      },
      {
         "name": "content_genre",
         "type": "forward"
      },
      {
         "name": "did",
         "type": "from-query-parameter",
         "value": "device_id"
      },
      {
         "name": "ip",
         "type": "from-variable",
         "value": "$CLIENT_IP"
      },
      {
         "name": "break_duration",
         "type": "from-variable",
         "value": "$ADBREAK_DURATION_S"
      },
      {
         "name": "ua",
         "type": "from-header",
         "value": "User-Agent"
      }
   ]
}

The type property will be one of the following, matching the ones shown in the Web App in the previous section:

• custom, for static values
• forward, for query parameters forwarded unmodified. Note how in this case, the value is ignored and therefore not necessary
• from-query-parameter, for values extracted from query parameters on the incoming request
• from-header, for values extracted from headers on the incoming request
• from-variable, for values calculated by the platform

System Variables

The following system variables can be used when type is set to from-variable:

URL-encoding

To ensure proper parsing of the macro values by the ad server, they should be URL-encoded. The following rules apply:

• Values extracted from headers (from-header) or obtained via system variables (from-variable) will be automatically URL-encoded by broadpeak.io
• Values extracted from query parameters (from-query-parameter) or forwarded (forward) will not be URL-encoded to avoid double encoding. Therefore those values must come already properly URL-encoded in in the streaming request to broadpeak.io.

❗️

You must URL-encode any query parameter added to the streaming request to broadpeak.ioto ensure that it is handled correctly and passed in the appropriate way to the ad server

Advanced usage

Service and session identifiers

For ease of troubleshooting complete flows, it can be useful to send the service hash and/or the session ID to the ad server. Since those appear on the resolved streaming URL, they can be used in the same way as other variables.

For example, to send them as sess and serv:

json

    {
      "name": "sess",
      "type": "from-query-parameter",
      "value": "bpkio_sessionid"
    },
    {
      "name": "serv",
      "type": "from-query-parameter",
      "value": "bpkio_serviceid"
    },

custom type

The custom type can also be used to concatenate multiple incoming values into a single query parameter going to the ad server. To refer to those values, use the following logic:

• Values from incoming query parameters are referred with $arg_<param-name>
• Values from incoming headers are referred with $http_<header-name>
• For values from system variables, use the $-name from the table above.

The references can only contain letters, numbers and underscores. If the header or param name contains dashes, convert them to underscores, eg. $arg_device_id for incoming query parameter device-id

Note also that the names are not case sensitive. Therefore $arg_deviceid is equivalent to $arg_deviceId and will extract values equally from deviceid and deviceId

To avoid ambiguity when concatenating referenced values with static strings, surround the reference name with curly brackets, eg. ${arg_name}

For example, imagine that you want to send to the ad server query parameter device the result of concatenating the value of incoming query param device-id with a custom header X-Device-Type and the client IP, into a string with a prefix and suffix, you would set the following in the ad server config:

JSON

      {
         "name": "device",
         "type": "custom",
         "value": "id_${arg_device_id}-${http_X_Device_Type}/${CLIENT_IP}-prod"
      }

Forwarded Headers

By default, the following headers are forwarded from the client request (coming through your CDN) to the Ad Server:

• X-Forwarded-For: The client IP can be retrieved from here if the CDN is configured to pass it through.
• User-Agent: The user-agent of the device if provided by the CDN in the request.