Using domain variables

With dynamic domain variables, you can use multiple domains, such as the my-ads-server.com part of the URL http://my-ads-server.com, with the player parameters in your configuration. This makes it possible for you to use more than one content source or ad decision server (ADS) in a single configuration.

You can use domain variables with any parameter that contains a URI:

• AdDecisionServerUrl

• AdSegmentUrlPrefix

• ContentSegmentUrlPrefix

• LivePreroll.AdDecisionServerUrl

• VideoContentSourceUrl

Domain variables are used alongside configuration aliases to perform dynamic variable replacement. Configuration aliases map a set of aliases and values to the player parameters that are used for dynamic domain configuration.

Creating configuration aliases to use as dynamic variables

Before you start to use domain variables, you create configuration aliases for your configuration. You use the configuration aliases as domain replacement variables at session initialization time. For example, you can use configuration aliases to dynamically configure an origin URL during session initialization.

Creating configuration aliases

To create configuration aliases to use for domain replacement using the MediaTailor console, perform the following procedure.

To create configuration aliases using the console

1. Open the MediaTailor console at https://console.aws.amazon.com/mediatailor/.

2. On the Configuration aliases section on the Configurations page, choose Add player parameter.

3. Type the player parameter name that you would like to use as a dynamic variable for domain replacement. You must prefix the name with player_params..

4. Choose OK.

   AWS Elemental MediaTailor displays the new parameter in the table in the Configuration aliases section.

5. Now, you'll add an alias and value. Select the player parameter that you just named. This expands the section below the parameter name.

   Select Add new alias.

6. Enter an Alias key and Value. MediaTailor uses Value as the replacement value for the domain variable.

Using configuration aliases to dynamically configure domains for a session

After you set up the configuration aliases, you can use them as replacement variables for domains in your session initialization request. This enables you to dynamically configure the domains for your session.

Restrictions

Note the following restrictions when using configuration aliases:

• All dynamic variables used in the domain must be defined as a ConfigurationAliases dynamic variable.

• The player parameter variables must be prefixed with player_params.. For example, player_params.origin_domain.

• The list of aliased values must be exhaustive for every player parameter.

• If a request is made for a dynamic value that's used in the domain, and that request either doesn’t specify the dynamic variable or one of the preconfigured aliases for that variable, then the request will fail with an HTTP 400 status code.

Example of usage

Here's an example of a configuration that includes configuration aliases and dynamic domain variables. Pay special attention to the player parameter variables, such as [player_params.origin_domain], in the AdDecisionServerUrl and VideoContentSourceUrl parameter domains.

PUT /playbackConfiguration
   {
       "Name": "aliasedConfig",
       ...
       "AdDecisionServerUrl": "https://abc.execute-api.us-west-2.amazonaws.com/ads?sid=[session.id]&ad_type=[player_params.ad_type]",
       "VideoContentSourceUrl": "https://[player_params.origin_domain].mediapackage.[player_params.region].amazonaws.com/out/v1/[player_params.endpoint_id]",
       ...
       "ConfigurationAliases": {
           "player_params.origin_domain": {
               "pdx": "abc",
               "iad": "xyz"
           },
           "player_params.region": {
               "pdx": "us-west-2",
               "iad": "us-east-1"
           },
           "player_params.endpoint_id": {
               "pdx": "abcd",
               "iad": "wxyz"
           },
           "player_params.ad_type": {
               "customized": "abc12345",
               "default": "defaultAdType"
           },
       },
       ...
   } 

Using the preceding configuration, create a session initialization request, specifying the player variables and aliases:

POST master.m3u8
   {
       "playerParams": {
           "origin_domain": "pdx",
           "region": "pdx",
           "endpoint_id": "pdx",
           "ad_type": "customized"
       }
   }

MediaTailor replaces the alias strings with the mapped values in the configuration aliases configuration.

The request to the ADS looks like this:

https://abc.execute-api.us-west-2.amazonaws.com/ads?sid=[session.id]&ad_type=abc12345

The request to the VideoContentSource looks like this:

https://abc.mediapackage.us-west-2.amazonaws.com/out/v1/abcd