View a markdown version of this page

Configuring the ADS request - AWS Elemental MediaTailor
FieldsTemplate syntaxForwarding Accept-LanguagePOST with JSON bodyHttpRequest limitations

Configuring the ADS request

Use AdDecisionServerConfiguration to control how AWS Elemental MediaTailor calls your ad decision server (ADS). This ensures your ADS receives the context it needs to return relevant ads. Use it to configure any of the following:

  • A POST body (for example, an OpenRTB bid request).

  • Custom request headers (for example, Accept-Language).

  • A compressed payload.

By default, your ADS receives a GET request at the URL specified by AdDecisionServerUrl. To customize the request beyond that default, configure the AdDecisionServerConfiguration field on the playback configuration.

Use AdDecisionServerConfiguration.HttpRequest to configure the ADS request. The Headers and Body fields support dynamic variables, which MediaTailor substitutes with session-scoped values at request time.

HttpRequest fields

The following table describes the fields under AdDecisionServerConfiguration.HttpRequest.

Field Type Description
Method String enum The HTTP method MediaTailor uses when it calls the ADS. Valid values are GET and POST. Defaults to GET if omitted.
Headers Map of string to string Custom HTTP request headers to attach to the outbound ADS call. Header values support dynamic variable substitution using the {{variable}} template syntax (see Template variable syntax). MediaTailor sends these headers on both GET and POST requests.
Body String The request body template. Use this field only when Method is POST. Supports dynamic variable substitution using the {{variable}} template syntax. If a Content-Type header is set in Headers and includes application/json, MediaTailor JSON-escapes substituted values automatically. Otherwise, MediaTailor substitutes values as plain text.
CompressionMethod String enum The compression to apply to the request body. Valid values are NONE and GZIP. Defaults to NONE. When set to GZIP, MediaTailor compresses the interpolated body and sets the Content-Encoding: gzip header on the request. Only applies to POST requests.

Template variable syntax

Headers and Body both support dynamic variable substitution using the {{variable}} template syntax. This is different from the [variable] syntax used by AdDecisionServerUrl. The following table summarizes the two conventions.

Where you reference variables Syntax
AdDecisionServerUrl [variable] – for example, [session.user_agent]
AdDecisionServerConfiguration.HttpRequest.Headers {{variable}} – for example, {{session.user_agent}}
AdDecisionServerConfiguration.HttpRequest.Body {{variable}} – for example, {{session.uuid}}

All dynamic variables that MediaTailor supports work in both locations. These include session variables, SCTE-35 variables, player parameters, and configuration aliases. Only the delimiter differs. For the complete list of supported variables, see MediaTailor session variables for ADS requests and MediaTailor player variables for ADS requests.

Forwarding Accept-Language as a request header

To serve language-specific ads, forward the viewer's language preference to your ADS. The following playback configuration passes the Accept-Language header (captured at session initialization) as an HTTP request header on every ADS call:

{
    "Name": "customerConfig",
    "VideoContentSourceUrl": "https://origin.example.com/",
    "AdDecisionServerUrl": "https://ads.example.com/vast",
    "AdDecisionServerConfiguration": {
        "HttpRequest": {
            "Method": "GET",
            "Headers": {
                "Accept-Language": "{{session.accept_language}}"
            }
        }
    }
}

MediaTailor auto-populates session.accept_language from the Accept-Language HTTP header that the player sends on the manifest request. Header lookup is case-insensitive. If the player does not send an Accept-Language header, session.accept_language is empty and the outbound header value is empty.

CDN and proxy requirements

If you use a CDN or proxy in front of the manifest endpoint, configure it to forward the Accept-Language header. This ensures the player's language preference reaches MediaTailor.

The CloudFront managed policy Managed-Elemental-MediaTailor-PersonalizedManifests does not forward this header. Use a policy that does (such as AllViewer) or add the header to a custom origin request policy allowlist.

Sending a POST request with a JSON body

The following playback configuration sends a POST request with a JSON body and a matching Content-Type header:

{
    "Name": "customerConfig",
    "VideoContentSourceUrl": "https://origin.example.com/",
    "AdDecisionServerUrl": "https://ads.example.com/ortb",
    "AdDecisionServerConfiguration": {
        "HttpRequest": {
            "Method": "POST",
            "Headers": {
                "Content-Type": "application/json",
                "Accept-Language": "{{session.accept_language}}"
            },
            "Body": "{\"id\": \"{{session.uuid}}\", \"user\": {\"ua\": \"{{session.user_agent}}\", \"ip\": \"{{session.client_ip}}\"}}",
            "CompressionMethod": "GZIP"
        }
    }
}

Because Content-Type contains application/json, MediaTailor JSON-escapes substituted values so special characters (quotes, backslashes) in variable values do not break the JSON document. MediaTailor then gzip-compresses the interpolated body and sets Content-Encoding: gzip on the outbound request.

HttpRequest limitations

The following limitations apply to AdDecisionServerConfiguration.HttpRequest:

  • MediaTailor applies CompressionMethod only when Method is POST.

  • Variable substitution in Headers and Body uses {{variable}} syntax. Substitution in AdDecisionServerUrl uses [variable] syntax. The two are not interchangeable.

  • Variables that are unresolved at request time render as an empty string in both headers and body.