Bid construction and templating

This page explains how MediaTailor builds an OpenRTB bid request from your template, how variable interpolation works, and what values MediaTailor sets automatically.

Configuration fields

When you enable Yield Optimization on a playback configuration, you provide four fields:

How the bid request is constructed

When an ad break has unfilled duration remaining, MediaTailor constructs the bid request in these steps:

Console default template

When you enable Yield Optimization in the MediaTailor console, the following pre-filled template is provided as a starting point. You should customize the values for your application:

{
  "imp": [
    {
      "bidfloor": 5
    }
  ],
  "app": {
    "id": "{{player_params.app_id}}",
    "name": "{{player_params.app_name}}",
    "bundle": "{{player_params.bundle}}",
    "storeurl": "{{player_params.storeurl}}",
    "domain": "{{player_params.domain}}",
    "content": {
      "genre": "{{asset.genre}}",
      "contentrating": "{{asset.content_rating}}"
    }
  },
  "device": {
    "dnt": "{{player_params.dnt}}",
    "ua": "{{session.user_agent}}",
    "ip": "{{session.client_ip}}",
    "ifa": "{{player_params.device_ifa}}",
    "w": "{{player_params.device_width}}",
    "h": "{{player_params.device_height}}",
    "language": "{{player_params.language}}",
    "model": "{{player_params.model}}",
    "os": "{{player_params.os}}",
    "osv": "{{player_params.osv}}",
    "devicetype": "{{player_params.devicetype}}",
    "make": "{{player_params.make}}"
  },
  "user": {
    "consent": "{{player_params.consent}}"
  },
  "regs": {
    "gdpr": "{{player_params.gdpr}}",
    "us_privacy": "{{player_params.us_privacy}}",
    "gpp": "{{player_params.gpp_consent}}",
    "gpp_sid": "{{player_params.gpp_sid}}"
  }
}

Field-by-field explanation:

Template interpolation (Mustache templating)

Your ORTB template uses Mustache templating syntax for dynamic value substitution. Placeholders use double curly brackets {{ }}.

Available template variables

Your ORTB template can use the same dynamic variables available in ADS URL templates. These include session variables (for example, {{session.user_agent}}, {{session.client_ip}}), player parameters ({{player_params.*}}), asset metadata ({{asset.*}}), avail context ({{avail.*}}), and SCTE signal data ({{scte.*}}).

For the complete list of available variables and their descriptions, see MediaTailor dynamic ad variables for ADS requests. For how MediaTailor URL-decodes player parameter values before substituting them into the template, see Encoding and decoding behavior later on this page.

The most commonly used variables in ORTB templates are:

How to pass player parameters

There are two ways to pass player parameters during session initialization.

Method 1: POST request with JSON body (recommended)

POST https://<mediatailor-endpoint>/v1/session/<config-hash>/<origin-id>/master.m3u8
Content-Type: application/json

{
  "playerParams": {
    "app_id": "558775_example",
    "slot_id": "608109df-2378-4bc5-8da5-24bc355f01a4",
    "os": "Tizen",
    "make": "Samsung",
    "model": "Tizen TV",
    "language": "en",
    "us_privacy": "1YNY"
  }
}

This method is preferred because it avoids URL-encoding issues with complex values like user agent strings.

Method 2: URL query parameters

GET https://<mediatailor-endpoint>/v1/session/<config-hash>/<origin-id>/master.m3u8
  ?playerParams.app_id=558775_example

With this method, values must be URL-encoded. MediaTailor URL-decodes them before interpolation.

Encoding and decoding behavior

MediaTailor performs one level of URL decoding on player parameter values before interpolating them into the template. This applies regardless of how the parameters are passed (POST body or URL query params).

Examples of decoded values:

Key points:

What happens when a variable is missing

If the player does not send a parameter referenced in your template (for example, {{player_params.app_name}} but no app_name in the player params), the placeholder resolves to an empty string "".

Impact: If the empty string is in a mandatory field (like app.bundle), the bid request fails with BidRequestConfigurationError. If it's in an optional field, APS receives an empty value which may cause a no-bid (HTTP 204) response.

What MediaTailor sets automatically

The following fields are always set by MediaTailor using values from your console configuration and the current avail context. If you include these in your template, your values are overridden:

Next steps