# MediaTailor manifest query parameters
<a name="manifest-query-parameters"></a>

AWS Elemental MediaTailor handles query parameters for different purposes: manifest query parameters for CDN routing and authorization, and other query parameters that may be used for origin-specific functionality.

AWS Elemental MediaTailor preserves query parameters from session initialization and appends them to personalized manifest URLs and other assets. Use this functionality when you have a Content Delivery Network (CDN) between MediaTailor and the client player.

Use manifest query parameters when your CDN needs the query parameters for the following:
+ Dynamic routing to different MediaTailor endpoints
+ Token authorization

**Client-side vs CDN behavior**  
MediaTailor appends query parameters for client-side reporting endpoints, but does not append them for CDN segments. The updated functionality provides more comprehensive support for query parameters across various MediaTailor assets, enhancing flexibility for CDN routing and authorization use cases.

MediaTailor appends query parameters for client-side reporting endpoints, but it doesn't append the query parameters for the CloudFront (or other CDN) segments.

To use parameter preservation, contact [AWS Support](https://aws.amazon.com/premiumsupport/) to request that manifest query parameter pass through be enabled. 

The behavior varies between HLS and DASH, and between explicit and implicit session initialization. The following topics describe how to configure session initialization requests so that MediaTailor passes through parameters to the manifest:

# MediaTailor query parameter handling for origins
<a name="origin-query-parameters"></a>

AWS Elemental MediaTailor handles query parameters differently depending on their purpose. Manifest query parameters (prefixed with `manifest.`) are used for CDN routing and authorization, while other query parameters can be used for origin-specific functionality.

**Time-shifted viewing with MediaPackage**  
For time-shifted viewing functionality with MediaPackage, you can include `start` and `end` parameters in your requests. These parameters define specific content windows for startover and catch-up viewing.

**Example time-shifted viewing request**  
Include start and end parameters in your manifest request for time-shifted viewing:  

```
GET /v1/master/111122223333/originId/index.m3u8?start=2024-08-26T10:00:00Z&end=2024-08-26T11:00:00Z
```

**Parameter behavior during sessions**  
Query parameters are processed at session initialization. For time-shifted viewing or other origin-specific features:
+ **Session initialization:** Include required parameters with the initial manifest request
+ **Parameter persistence:** Parameters are associated with the session and maintained throughout playback
+ **Changing parameters:** To modify time-shift windows or other parameters, create a new session with updated values

**Important**  
The specific handling of query parameters depends on your origin configuration and the parameters your content origin supports. For MediaPackage integration, ensure your CDN is configured to forward the necessary query parameters as described in [Configure essential query parameters](mediapackage-integration.md#mediapackage-query-strings).

# MediaTailor parameter character restrictions and URL-encoding
<a name="manifest-query-parameters-character-restrictions"></a>

AWS Elemental MediaTailor supports specific characters in manifest query parameters. You can use URL-encoding for special characters.

**Supported characters with URL-encoding**  
The following special characters are supported with URL-encoding:
+ period (.) = %2E
+ dash (-) = %2D
+ underscore (\$1) = %5F
+ percent (%) = %25
+ tilde (\$1) = %7E
+ forward slash (/) = %2F
+ asterisk (\$1) = %2A
+ equals (=) = %3D
+ question (?) = %3F

**URL-encoding support**  
MediaTailor supports the percent (%) sign when you use it in URL-encoding (for example, hello%20world = hello world). You can use any URL-encoded characters, as long as they are valid URL-encodings according to the HTTP specification.

**Important**  
MediaTailor doesn't support double characters such as %%% or ==.

**Security considerations**  
MediaTailor implements the following security measures for parameter handling:

1. Input size limitations to prevent database bloat

1. Proper encoding and sanitization of user input

1. URL-encoding of input to prevent response corruption

**Topics**
+ [Origin query parameters](origin-query-parameters.md)
+ [MediaTailor character restrictions](manifest-query-parameters-character-restrictions.md)
+ [MediaTailor HLS implicit sessions](manifest-query-parameters-hls-implicit-session-initialization.md)
+ [MediaTailor DASH implicit sessions](manifest-query-parameters-dash-implicit-session-initialization.md)
+ [MediaTailor explicit session initialization](manifest-query-parameters-hls-and-dash-explicit-session-initialization.md)
+ [MediaTailor protocol-specific behavior](manifest-query-parameters-protocol-differences.md)
+ [MediaTailor CDN integration](manifest-query-parameters-cdn-integration.md)

# MediaTailor HLS implicit session initialization
<a name="manifest-query-parameters-hls-implicit-session-initialization"></a>

AWS Elemental MediaTailor includes query parameters in links to MediaTailor resources when your request includes query parameters with the key `manifest.*`. The following example shows this request format:

```
GET /v1/master/111122223333/originId/index.m3u8?manifest.test=123&other=456
```

Links don't include the `manifest.` prefix.

**Parameter application in HLS**  
For HLS implicit sessions, MediaTailor applies parameters to the following locations in the manifest hierarchy:
+ Multivariant playlist URLs
+ Media playlist URLs
+ Content segment URLs
+ Ad segment URLs
+ HLS initialization URLs

**Example multivariant playlist**  
The following example shows how MediaTailor includes the query parameters in the URL for the multivariant playlist:  

```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-MEDIA:LANGUAGE="eng",AUTOSELECT=YES,FORCED=NO,TYPE=SUBTITLES,URI="../../../manifest/111122223333/originId/session/1.m3u8?test=123",GROUP-ID="subtitles",DEFAULT=YES,NAME="caption_1"
#EXT-X-STREAM-INF:CODECS="avc1.640029,mp4a.40.2",AVERAGE-BANDWIDTH=2525657,RESOLUTION=960x540,SUBTITLES="subtitles",FRAME-RATE=29.97,BANDWIDTH=2665212
../../../manifest/111122223333/originId/session/0.m3u8?test=123
```

**Example media playlist**  
The following example shows how MediaTailor includes the query parameters in the URLs for the content segments:  

```
#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:7
#EXT-X-MEDIA-SEQUENCE:28716269
#EXT-X-DISCONTINUITY-SEQUENCE:0
#EXTINF:6.006,
https://origin.com/contentSegment_1.ts?originQueryParam=foo&test=123
#EXT-X-DISCONTINUITY
#EXTINF:6.006,
../../../../segment/111122223333/originId/session/0/2?test=123
```

# MediaTailor DASH implicit session initialization
<a name="manifest-query-parameters-dash-implicit-session-initialization"></a>

AWS Elemental MediaTailor creates a session for the client and redirects it with query parameters when the client makes a manifest request without a session. The following example shows this request format:

```
GET /v1/dash/111122223333/originId/index.mpd?manifest.test=123&other=456
```

MediaTailor creates a session for the client and redirects it with the query parameters:

```
/v1/dash/111122223333/originId/index.mpd?sessionId=session&test=123
```

**Parameter application in DASH**  
The DASH manifest response includes the query parameters in various locations, including content segments, ad segments, and initialization URLs. MediaTailor applies parameters to the following:
+ DASH manifest Location elements
+ SegmentTemplate initialization attributes
+ SegmentTemplate media attributes
+ Content segment URLs
+ Ad segment URLs

When the client makes the request, MediaTailor responds with a DASH manifest similar to the following example. The first period is a content period, so MediaTailor doesn't insert the manifest query parameter there. In the second period, which is an ad period, MediaTailor inserts the manifest query parameter into the `SegmentTemplate` element's `initialization` attribute and `media` attribute. The `Location` element also has the manifest query parameters.

```
<?xml version="1.0" encoding="UTF-8"?>
<MPD availabilityStartTime="2018-07-27T09:48:23.634000+00:00" id="201" minBufferTime="PT30S" minimumUpdatePeriod="PT15S" profiles="urn:mpeg:dash:profile:isoff-live:2011" publishTime="2023-02-14T23:37:43" suggestedPresentationDelay="PT25.000S" timeShiftBufferDepth="PT56.997S" type="dynamic" xmlns="urn:mpeg:dash:schema:mpd:2011" xmlns:scte35="urn:scte:scte35:2013:xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:mpeg:dash:schema:mpd:2011 http://standards.iso.org/ittf/PubliclyAvailableStandards/MPEG-DASH_schema_files/DASH-MPD.xsd">
    <BaseURL>https://origin.com/contentSegments/</BaseURL>
    <Location>https://mediatailor.com/v1/dash/111122223333/originId/index.mpd?test=123&aws.sessionId=session</Location>
    <Period duration="PT29.963S" id="28737823" start="PT143732873.178S">
        <AdaptationSet bitstreamSwitching="true" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1">
            <Representation bandwidth="2200000" codecs="avc1.640029" frameRate="30000/1001" height="540" id="1" width="960">
                <SegmentTemplate initialization="index_video_7_0_init.mp4?m=1611174111" media="index_video_7_0_$Number$.mp4?m=1611174111" presentationTimeOffset="4311986195351" startNumber="28737828" timescale="30000">
                    <SegmentTimeline>
                        <S d="180180" t="4311986911066"/>
                        <S d="3003" t="4311987091246"/>
                    </SegmentTimeline>
                </SegmentTemplate>
            </Representation>
        </AdaptationSet>
    </Period>
    <Period id="28737829_1" start="PT39925H48M23.141S">
        <BaseURL>https://mediatailor.com/v1/dashsegment/111122223333/originId/session/28737829/28737829_1/</BaseURL>
        <AdaptationSet bitstreamSwitching="false" frameRate="30000/1001" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1">
            <SegmentTemplate startNumber="1" timescale="90000"/>
            <Representation bandwidth="2200000" codecs="avc1.64001f" height="540" id="1" width="960">
                <SegmentTemplate initialization="asset_540_2_0init.mp4?test=123" media="asset_540_2_0_$Number%09d$.mp4?test=123" startNumber="1" timescale="90000">
                    <SegmentTimeline>
                        <S d="180180" r="6" t="0"/>
                        <S d="87087" t="1261260"/>
                    </SegmentTimeline>
                </SegmentTemplate>
            </Representation>
        </AdaptationSet>
    </Period>
</MPD>
```

# MediaTailor HLS and DASH explicit session initialization
<a name="manifest-query-parameters-hls-and-dash-explicit-session-initialization"></a>

AWS Elemental MediaTailor includes the `manifestParams` as query parameters in the multivariant playlist and tracking URLs in the response when the client makes an explicit session initialization request.

**Session initialization methods**  
For explicit session initialization, you can use either POST with request body or GET with query parameters:

1. **POST with Request Body:**

   ```
   POST /v1/session/111122223333/originId/index.m3u8
   {
       "adsParams": {"param1": "value1", "param2": "value2", "param3": "value3"},
       "manifestParams": {"test": "123"}
   }
   ```

1. **GET with Query Parameters:**

   ```
   GET /v1/session/111122223333/originId/index.m3u8?ads.param1=value1&ads.param2=value2&manifestParams.test=123
   ```

**Example session initialization request**  

```
POST /v1/session/111122223333/originId/index.m3u8
{
    "adsParams": {
        "param1": "value1",
        "param2": "value2",
        "param3": "value3"
    },
    "manifestParams": { 
        "test": "123"
    },
    "reportingMode": "client"
}
```

**Example manifest and tracking response**  

```
{
    "manifestUrl": "/v1/master/111122223333/originId/index.m3u8?aws.sessionId=session&test=123",
    "trackingUrl": "/v1/tracking/111122223333/originId/session?test=123"
}
```

Manifest responses for the session have the specific `manifestParams` in MediaTailor URLs similar to the previously described implicit session-initialization workflows. The key difference is that manifest parameters for explicit session initialization don't start with `manifest.`.

Manifest query parameters are immutable and you can only set them on session initialization. If a client makes multiple multivariant playlist requests for a single session, MediaTailor doesn't update the manifest query parameters after the first request.

**Parameter processing flow**  
You can only specify parameters once, at initialization time. Configuration aliases resolve to actual values before forwarding. For example: `player_params.ad_type=customized` resolves to `ad_type=abc12345` based on the ConfigurationAliases configuration.

# MediaTailor protocol-specific parameter behavior
<a name="manifest-query-parameters-protocol-differences"></a>

AWS Elemental MediaTailor handles manifest query parameters differently for HLS and DASH protocols. Each protocol type has specific application locations and processing methods.

**HLS vs DASH parameter handling comparison**  
The following table compares how MediaTailor handles manifest query parameters across HLS and DASH protocols:


| Aspect | HLS Behavior | DASH Behavior | 
| --- | --- | --- | 
| Parameter application | Applied directly to manifest URLs and segment URLs | Applied to Location elements, SegmentTemplate attributes, and segment URLs | 
| Manifest hierarchy | Multivariant playlist → Media playlists→ Segments | MPD → Periods → AdaptationSets → Representations | 
| Initialization URLs | Applied to HLS init URLs when present | Applied to SegmentTemplate initialization attributes | 
| Session handling | Parameters preserved across playlist updates | Parameters included in MPD Location element for session continuity | 
| Ad segment handling | Applied to ad segment URLs in media playlists | Applied to ad period SegmentTemplate media attributes | 

**Parameter application locations**  
MediaTailor applies manifest query parameters to the following locations:

## HLS parameter application
<a name="hls-parameter-application"></a>

For HLS streams, MediaTailor applies manifest query parameters to:
+ **Multivariant playlist URLs:** Parameters are appended to media playlist references
+ **Media playlist URLs:** Parameters are included in segment URLs within media playlists
+ **Content segment URLs:** All content segments include the manifest query parameters
+ **Ad segment URLs:** Ad segments receive parameters for CDN routing and authorization
+ **HLS initialization URLs:** Init segments include parameters when present in the stream
+ **Slate segment URLs:** Slate content includes parameters for consistent CDN behavior

**Example HLS parameter application example**  
Given the session initialization:  

```
GET /v1/master/123456789/originId/index.m3u8?manifest.auth_token=abc123&manifest.region=us-west
```
The multivariant playlist includes parameters in media playlist references:  

```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-STREAM-INF:BANDWIDTH=2665212,RESOLUTION=960x540
../../../manifest/123456789/originId/session/0.m3u8?auth_token=abc123&region=us-west
```
The media playlist includes parameters in segment URLs:  

```
#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:7
#EXTINF:6.006,
https://origin.com/segment1.ts?auth_token=abc123&region=us-west
#EXTINF:6.006,
../../../../segment/123456789/originId/session/0/2?auth_token=abc123&region=us-west
```

## DASH parameter application
<a name="dash-parameter-application"></a>

For DASH streams, MediaTailor applies manifest query parameters to:
+ **MPD Location elements:** The Location element includes parameters for manifest refresh requests
+ **SegmentTemplate initialization attributes:** Init segment URLs include parameters
+ **SegmentTemplate media attributes:** Media segment URL templates include parameters
+ **Content segment URLs:** All content segments generated from templates include parameters
+ **Ad segment URLs:** Ad period segments include parameters for CDN integration
+ **Server-side reporting redirects:** 302 redirects to ad segments preserve parameters

**Example DASH parameter application example**  
Given the session initialization:  

```
GET /v1/dash/123456789/originId/index.mpd?manifest.auth_token=abc123&manifest.region=us-west
```
The DASH manifest includes parameters in multiple locations:  

```
<MPD>
    <Location>https://mediatailor.com/v1/dash/123456789/originId/index.mpd?auth_token=abc123&region=us-west&aws.sessionId=session</Location>
    <Period>
        <AdaptationSet>
            <Representation>
                <SegmentTemplate 
                    initialization="init.mp4?auth_token=abc123&region=us-west" 
                    media="segment_$Number$.mp4?auth_token=abc123&region=us-west"/>
            </Representation>
        </AdaptationSet>
    </Period>
</MPD>
```

# MediaTailor CDN integration and parameter routing
<a name="manifest-query-parameters-cdn-integration"></a>

AWS Elemental MediaTailor manifest query parameters enable sophisticated CDN integration scenarios. You can use them for dynamic routing, authorization, and load balancing.

**CDN routing use cases**  
Common CDN integration scenarios that benefit from manifest query parameters include the following:
+ **Geographic routing:** Route requests to region-specific MediaTailor endpoints based on viewer location
+ **Token-based authorization:** Pass authorization tokens through the CDN to MediaTailor for secure content access
+ **Load balancing:** Distribute traffic across multiple MediaTailor endpoints using CDN routing logic
+ **A/B testing:** Route different user segments to different MediaTailor configurations for testing
+ **Device-specific optimization:** Route requests based on device type or capabilities

**Parameter preservation across CDN layers**  
MediaTailor ensures that manifest query parameters are preserved across multiple CDN layers and request types:

1. **Initial request:** Parameters are extracted from the session initialization request

1. **Manifest generation:** Parameters are applied to all relevant URLs in the manifest

1. **Segment requests:** Parameters are included in all segment URLs for consistent CDN behavior

1. **Ad insertion:** Parameters are preserved during ad insertion and segment replacement

**Example CDN authorization flow**  
The following example demonstrates a complete CDN authorization flow using manifest query parameters:  

1. Client requests manifest with authorization token:

   ```
   GET https://cdn.example.com/mediatailor/v1/master/123456789/originId/index.m3u8?manifest.auth_token=jwt_token_here&manifest.user_id=12345
   ```

1. CDN forwards request to MediaTailor with parameters:

   ```
   GET https://mediatailor.amazonaws.com/v1/master/123456789/originId/index.m3u8?manifest.auth_token=jwt_token_here&manifest.user_id=12345
   ```

1. MediaTailor generates manifest with parameters applied to all URLs:

   ```
   #EXTM3U
   #EXT-X-STREAM-INF:BANDWIDTH=2665212
   ../../../manifest/123456789/originId/session/0.m3u8?auth_token=jwt_token_here&user_id=12345
   ```

1. Subsequent segment requests include parameters for CDN authorization:

   ```
   GET https://cdn.example.com/mediatailor/segment/123456789/originId/session/0/1?auth_token=jwt_token_here&user_id=12345
   ```