# MediaTailor configuration aliases overview
<a name="configuration-aliases-overview"></a>

AWS Elemental MediaTailor configuration aliases enable dynamic variable replacement in URL domains and other supported fields. Use this feature to use multiple domains and dynamically configure URLs during session initialization.

## Use cases
<a name="configuration-aliases-use-cases"></a>

Configuration aliases enable sophisticated multi-configuration architectures for the following scenarios:
+ **Geographic routing:** Route requests to different origins or ad servers based on viewer location using region-specific aliases. For implementation guidance, see [CloudFront Origin Failover](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/high_availability_origin_failover.html).
+ **Content-based routing:** Direct different content types to specialized origins or processing pipelines. For routing behavior configuration, see [Set up CDN routing behaviors for MediaTailor](cdn-routing-behaviors.md).
+ **Failover scenarios:** Implement backup origins and ad servers with automatic failover using alias switching. For detailed implementation, see [Implement multi-Region resilience for MediaTailor with MQAR](media-quality-resiliency.md) and [Plan your CDN integration for AWS Elemental MediaTailor](planning-cdn-integration.md).
+ **A/B testing:** Test different ad servers, origins, or configurations by routing traffic based on player parameters. For load testing guidance, see [Prepare and run performance tests for Amazon CloudFront with real user monitoring](https://aws.amazon.com/blogs/networking-and-content-delivery/prepare-and-run-performance-tests-for-amazon-cloudfront-with-real-user-monitoring/).
+ **Device-specific optimization:** Optimize content delivery and ad serving for different device types or capabilities. For comprehensive guidance, see [Set up manifest filtering with MediaTailor, MediaPackage, and CDN](cdn-emp-manifest-filtering.md).
+ **Load balancing:** Distribute load across multiple origins or ad servers using dynamic routing. For implementation guidance, see [Implement multi-Region resilience for MediaTailor with MQAR](media-quality-resiliency.md) and [Plan your CDN integration for AWS Elemental MediaTailor](planning-cdn-integration.md).

## Supported fields
<a name="configuration-aliases-supported"></a>

You can use dynamic variables in the following configuration fields:
+ `VideoContentSourceUrl`
+ `AdDecisionServerUrl`
+ `LivePreroll.AdDecisionServerUrl`
+ `AdSegmentUrlPrefix`
+ `ContentSegmentUrlPrefix`
+ `TranscodeProfileName`
+ `SlateAdUrl`
+ `StartUrl`
+ `EndUrl`

The following sections describe how to use configuration aliases.

**Topics**
+ [Use cases](#configuration-aliases-use-cases)
+ [Supported fields](#configuration-aliases-supported)
+ [Creating and using](creating-configuration-aliases.md)
+ [Example flow](configuration-aliases-examples.md)

# Creating and using configuration aliases with MediaTailor
<a name="creating-configuration-aliases"></a>

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.

**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 domain variables in critical URLs (`VideoContentSourceUrl`, `AdSegmentUrlPrefix`, `ContentSegmentUrlPrefix`).
+ If a request is made for a domain variable in critical URLs that either doesn't specify the dynamic variable or uses an invalid alias, the request will fail with an HTTP `400` status code. Non-critical fields (`SlateAdUrl`, `TranscodeProfileName`, bumper URLs) will log warnings but not fail the request.

**Fallback behavior for missing aliases**  
When configuration aliases are not found or are invalid, MediaTailor implements the following fallback behavior:
+ **Domain variables:** If a domain variable alias is missing or invalid, the request fails with HTTP 400 status code. All domain variables must have valid aliases defined.
+ **Non-domain variables:** For variables used in non-domain portions of URLs (such as path elements or query parameters), missing aliases result in empty string replacement.
+ **Configuration validation:** MediaTailor validates that all required aliases are present during configuration creation and update operations.

## Step 1: Create configuration aliases
<a name="dynamic-domains-creating-configuration-alias"></a>

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

------
#### [ Console ]

**To create configuration aliases using the console**

1. Open the MediaTailor console at [https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/).

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

1. For **Player parameter**, enter the name of the player parameter that you want to use as a dynamic variable. For example, `player_params.origin_domain`. 

1. For **Aliases**, enter the aliases and their values that you want to use for the player parameter. 

1. Choose **OK**. 

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

1. Repeat the preceding steps to add more player parameters. 

1. Choose **Save**. 

------
#### [ API ]

**To create configuration aliases using the API**  
When you create or update a MediaTailor configuration, use the `ConfigurationAliases` parameter with the following JSON structure: 

```
{
                "ConfigurationAliases": {
                "player_params.origin_domain": {
                "pdx": "abc.mediapackage.us-west-2.amazonaws.com",
                "iad": "xyz.mediapackage.us-east-1.amazonaws.com"
                },
                "player_params.ad_type": {
                "customized": "abc12345",
                "default": "defaultAdType"
                }
                }
                }
```

------

## Step 2: Use configuration aliases in session initialization
<a name="dynamic-domains-using-configuration-alias"></a>

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.

**Example Basic configuration aliases example**  
Here's a basic example of a configuration that includes configuration aliases and dynamic domain variables:  

```
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"
        }
    }
}
```

**Example Session initialization with aliases**  
Using the preceding configuration, a session initialization request using the player variables and aliases would look similar to the following:  

```
POST index.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 will look like the following:  

```
https://abc.execute-api.us-west-2.amazonaws.com/ads?sid=[session.id]&ad_type=abc12345
```
The request to the origin for the manifests will look like the following:  

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

# Configuration alias with MediaTailor use example
<a name="configuration-aliases-examples"></a>

The following examples show how a complete MediaTailor configuration with configuration aliases, a session initialization request with aliases, and the processing flow for aliases.

**Example Complete configuration with aliases**  
The following example shows a complete configuration that includes configuration aliases and dynamic domain variables:   

```
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]",
    
    "AdSegmentUrlPrefix": "https://[player_params.ad_cdn_domain]/ads/",
    "ContentSegmentUrlPrefix": "https://[player_params.content_cdn_domain]/content/",
    "TranscodeProfileName": "[player_params.transcode_profile]",
    "SlateAdUrl": "https://[player_params.slate_domain]/slate/[player_params.slate_type].mp4",
    "StartUrl": "https://[player_params.tracking_domain]/start?session=[session.id]",
    "EndUrl": "https://[player_params.tracking_domain]/end?session=[session.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"
        },
        "player_params.ad_cdn_domain": {
            "pdx": "ads-west.cdn.example.com",
            "iad": "ads-east.cdn.example.com"
        },
        "player_params.content_cdn_domain": {
            "pdx": "content-west.cdn.example.com",
            "iad": "content-east.cdn.example.com"
        },
        "player_params.transcode_profile": {
            "mobile": "mobile_optimized",
            "desktop": "high_quality",
            "tv": "4k_profile"
        },
        "player_params.slate_domain": {
            "pdx": "slate-west.example.com",
            "iad": "slate-east.example.com"
        },
        "player_params.slate_type": {
            "standard": "default_slate",
            "branded": "brand_slate"
        },
        "player_params.tracking_domain": {
            "pdx": "tracking-west.example.com",
            "iad": "tracking-east.example.com"
        }
    }
}
```

**Example Session initialization with aliases**  
The following example shows a session initialization request that specifies the player variables and aliases:   

```
POST master.m3u8
{
    "playerParams": {
        "origin_domain": "pdx",
        "region": "pdx", 
        "endpoint_id": "pdx",
        "ad_type": "customized",
        "ad_cdn_domain": "pdx",
        "content_cdn_domain": "pdx",
        "transcode_profile": "mobile",
        "slate_domain": "pdx",
        "slate_type": "branded",
        "tracking_domain": "pdx"
    }
}
```

**Example Parameter processing flow**  
In the following example, MediaTailor replaces the alias strings with the mapped values in the configuration aliases. The processing results in the following requests:   
+ ADS request:

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

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

  ```
  https://ads-west.cdn.example.com/ads/
  ```
+ ContentSegmentUrlPrefix:

  ```
  https://content-west.cdn.example.com/content/
  ```
+ TranscodeProfileName:

  ```
  mobile_optimized
  ```
+ SlateAdUrl:

  ```
  https://slate-west.example.com/slate/brand_slate.mp4
  ```
+ StartUrl:

  ```
  https://tracking-west.example.com/start?session=[session.id]
  ```
+ EndUrl:

  ```
  https://tracking-west.example.com/end?session=[session.id]
  ```