# Using AWS Elemental MediaTailor to insert ads
<a name="configurations"></a>

A configuration is an object that you interact with in AWS Elemental MediaTailor. The configuration holds the mapping information for the origin server and the ad decision server (ADS). You can also define a default playback for MediaTailor to use when an ad isn't available or doesn't fill the entire ad avail.

If you use a content delivery network (CDN) with MediaTailor, you must set up the behavior rules in the CDN before you add CDN information to the configuration. For more information about setting up your CDN, see [Using a CDN to optimize MediaTailor ad personalization and content delivery](integrating-cdn.md).

**Topics**
+ [Supported audio and video codecs](#supportedcodecs)
+ [Understanding AWS Elemental MediaTailor ad insertion behavior](ad-behavior.md)
+ [MediaTailor server-guided ad insertion overview and implementation](server-guided.md)
+ [MediaTailor ad server integration requirements](vast.md)
+ [MediaTailor playback configuration management](working-with-configurations.md)
+ [Integrating a content source for MediaTailor ad insertion](integrating-origin.md)
+ [Integrating AWS Elemental MediaTailor with Google Ad Manager](gam-integration.md)
+ [Customizing ad break behavior with ad break suppression](ad-rules.md)
+ [MediaTailor bumper ad insertion](bumpers.md)
+ [MediaTailor pre-roll ad insertion](ad-behavior-preroll.md)
+ [MediaTailor slate ad insertion](slate-management.md)
+ [Prefetching ads](prefetching-ads.md)
+ [Using preconditioned ads with AWS Elemental MediaTailor](precondition-ads.md)
+ [MediaTailor dynamic ad variables for ADS requests](variables.md)
+ [MediaTailor manifest query parameters](manifest-query-parameters.md)
+ [Reporting ad tracking data](ad-reporting.md)
+ [Overlay ads](overlay-ads.md)
+ [Ad ID decoration](ad-id-decoration.md)

## Supported audio and video codecs
<a name="supportedcodecs"></a>

MediaTailor supports the following codecs.
+ Audio codecs: mp4a, ac-3, and ec-3
+ Video codecs: h.264 (AVC), h.265 (HEVC), av01 (AV1)

# Understanding AWS Elemental MediaTailor ad insertion behavior
<a name="ad-behavior"></a>

AWS Elemental MediaTailor stitches ads into live or video on demand (VOD) content by either replacing or inserting ads into the origin manifest. Whether ads are inserted or replaced depends on how the ad breaks are configured in the origin manifest, and whether the content is VOD or live. An ad break is the time period during programming when commercials are shown, while ad avails are the specific units of advertising time within an ad break that can be filled with ads.
+ With *ad replacement*, MediaTailor replaces content segments with ads. 
+ With *ad insertion*, MediaTailor inserts ad content where segments don't exist.

For information about how MediaTailor stitches ads into live and VOD content, select the applicable topic.

**Topics**
+ [Ad stitching behavior for VOD](#ad-behavior-vod)
+ [Live ad stitching behavior](#ad-behavior-live)

## Ad stitching behavior for VOD
<a name="ad-behavior-vod"></a>

MediaTailor inserts or replaces ads in VOD content based on how ad markers are configured in the origin manifest, and if the ad decision server (ADS) sends VMAP responses.

For ad behavior by marker configuration, see the following sections.

### If ad markers are present
<a name="markers-present"></a>

AWS Elemental MediaTailor inserts ads where SCTE-35 ad markers are present in the origin manifest. Ad markers with an `EXT-X-CUE-OUT` value of `0` duration indicate ad insertion. 

#### HLS ad marker guidelines
<a name="markers-present-hls"></a>

 Follow these guidelines for post-roll and ad pod SCTE signaling: 

##### Pre-roll ads
<a name="post-roll-ad-markers"></a>

For HLS post-rolls, `CUE-OUT/IN` markers must precede the last content segment. This is because the HLS spec requires tag decorators to be explicitly declared before a segment. 

For example, consider the following declaration. 

```
#EXT-X-CUE-OUT: 0
#EXT-X-CUE-IN
#EXTINF:4.000,
Videocontent.ts
#EXT-X-ENDLIST
```

AWS Elemental MediaTailor inserts a post-roll like the following.

```
#EXTINF:4.000,
Videocontent.ts
#EXT-X-DISCONTINUITY
#EXTINF:3.0,
Adsegment1.ts
#EXTINF:3.0,
Adsegment2.ts
#EXTINF:1.0,
Adsegment3.ts
#EXT-X-ENDLIST
```

**Example 2: Ad pods**  
 `CUE-OUT/IN` tags must be explicitly attached to a segment. You can't use multiple `CUE-OUT/IN` tags in succession to mimic ad pod behavior.  
For example, the following declaration is a valid use of `CUE-OUT/IN` to portray an ad pod.  

```
#EXT-X-CUE-OUT: 0
#EXT-X-CUE-IN
#EXTINF:4.000,
Somecontent1.ts
#EXT-X-CUE-OUT: 0
#EXT-X-CUE-IN
#EXTINF:4.000,
Somecontent2.ts
#EXT-X-CUE-OUT: 0
#EXT-X-CUE-IN
#EXTINF:4.000,
Videocontent.ts
```
The preceding declaration results in an output like the following.   

```
Ad 1
Somecontent.ts
Ad 2
Somecontent2.ts
Videocontent.ts
Post-Roll Ad 3
```
The following declaration is invalid.  

```
#EXT-X-CUE-OUT: 0
#EXT-X-CUE-IN
#EXT-X-CUE-OUT: 0
#EXT-X-CUE-IN
#EXT-X-CUE-OUT: 0
#EXT-X-CUE-IN
#EXTINF:4.000,
Videocontent.ts
```

### If no ad markers are present
<a name="no-markers"></a>

Ad markers are the recommended way of signaling ad breaks in a manifest. However, ad markers aren't required. If the manifest doesn't contain ad markers for DASH or HLS, MediaTailor makes a single call to the ADS and creates ad breaks based on the response:
+ If the ADS sends a VAST response, then MediaTailor inserts all ads from the response in an ad break at the start of the manifest. This is a pre-roll.
+ If the ADS sends a VMAP response, then MediaTailor uses the ad break time offsets to create breaks and insert them throughout the manifest at the specified times (pre-roll, mid-roll, or post-roll). MediaTailor uses all ads from each ad break in the VMAP response for each ad break in the manifest. 
**Note**  
When a segment overlaps an insertion point with VMAP for VOD content, MediaTailor rounds down to the nearest insertion point. 
**Tip**  
If you want to create mid-roll ad breaks but your ADS doesn't support VMAP, then ensure that there are ad markers in the manifest. MediaTailor inserts ads at the markers, as described in the following sections.

**Note**  
For server-guided ad insertion methods, MediaTailor inserts pre-roll ads at the top of the manifest and the player plays them before other ad types.

## Live ad stitching behavior
<a name="ad-behavior-live"></a>

In live streams, AWS Elemental MediaTailor always performs ad replacement, preserving the total time between the ad markers as closely as possible. When ad markers include the `DURATION` attribute, MediaTailor uses the value to determine the duration of the ad break. Every `CUE-OUT` indicator must have a duration or a matching `CUE-IN` indicator in live workflows. 

MediaTailor performs ad replacement for HLS and DASH live content. For information on how MediaTailor calculates ad break placement and timing, see [HLS supported ad markers](hls-ad-markers.md) and [DASH ad markers](dash-ad-markers.md). 

### Ad selection and replacement
<a name="ad-behavior-live-ad-selection"></a>

AWS Elemental MediaTailor includes ads from the ad decision server (ADS) VAST response as follows: 
+ If a duration is specified, MediaTailor selects a set of ads that fit into the duration and includes them. 
+ If no duration is specified, MediaTailor plays as many ads as it can until it encounters an ad marker that indicates a return to the main content.

AWS Elemental MediaTailor adheres to the following guidelines during live ad replacement: 
+ MediaTailor tries to play complete ads, without clipping or truncation.
+ Whenever MediaTailor encounters an ad marker that indicates an end to the ad break, it returns to the underlying content. This can mean shortening an ad that is currently playing. 
+ At the end of the duration, MediaTailor returns to the underlying content.
+ If MediaTailor runs out of ads to play for the duration of an ad break it either plays the slate, if one is configured, or resumes playback of the underlying content stream. This usually happens when there aren't enough transcoded ads to fill up the duration of the ad break. 

  
**Tip**  
You can define the limit of unfilled ad time allowed in an break with the personalization threshold configuration setting. For more information, see the [PlaybackConfiguration reference](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_PutPlaybackConfiguration.html#mediatailor-PutPlaybackConfiguration-request-PersonalizationThresholdSeconds).

### Live preroll for server-guided ad insertion
<a name="ad-behavior-live-preroll-sgai"></a>

Live preroll works differently for server-guided ad insertion methods compared to server-side ad insertion:

Server-side ad insertion (stitched mode)  
Preroll ads replace part of the live content at the beginning of each viewer's session. Each viewer sees preroll at different times based on when they join the stream.

Server-guided ad insertion methods  
MediaTailor places a preroll daterange tag at the top of all media manifests with `CUE="PRE,ONCE"` attributes. This causes players to request and play preroll ads once at the start of playback, despite sharing the same non-personalized manifest.

**Configuration requirements:**
+ **Live preroll ad decision server:** Configure a VAST endpoint for preroll ads (can be different from mid-roll ads)
+ **Live preroll maximum allowed duration:** Set the maximum duration for preroll ads (optional - if omitted, all returned ads will be used)

**Technical implementation:**
+ Preroll daterange tag uses `START-DATE="1970-01-01T00:00:00.000Z"` (Unix epoch)
+ Asset list requests for preroll use the configured preroll ad decision server instead of the regular ADS
+ Players identify preroll requests through the `availId="aws-mediatailor-preroll-1"` in the asset list data

**Important**  
For live streams, preroll ads cover content rather than delaying it. Future versions may support content delay mode through additional configuration options.

**Note**  
Preroll behavior varies between live and VOD content for server-guided ad insertion. Live content requires explicit preroll configuration, while VOD content includes preroll by default using the regular ad decision server.

### Examples
<a name="ad-behavior-live-examples"></a>
+ If the ad break has a duration set to 70 seconds and the ADS response contains two 40-second ads, AWS Elemental MediaTailor plays one of the 40-second ads. In the time left over, it switches to the configured slate or underlying content. At any point during this process, if MediaTailor encounters a cue-in indicator, it cuts immediately to the underlying content. 
+ If the ad break has a duration set to 30 seconds and the shortest ad provided by the ADS response is 40 seconds, MediaTailor plays no ads. If an ad slate is configured, MediaTailor plays that for 30 seconds or until it encounters a cue-in indicator. Otherwise, MediaTailor plays the underlying content.

# MediaTailor server-guided ad insertion overview and implementation
<a name="server-guided"></a>

AWS Elemental MediaTailor server-guided ad insertion (SGAI) provides an alternative to server-side ad insertion by referencing ads as separate playlists rather than stitching them directly into media playlists. This approach improves performance through cacheable manifests and enables better scalability.

For information about how to use server-guided ad insertion with MediaTailor, choose the applicable topic from the following list.

## Enable in the playback configuration
<a name="enable-in-config"></a>

In order to allow players to use server-guided ad insertion, you must set `Insertion Mode` to `PLAYER_SELECT` in the MediaTailor playback configuration. This allows players to select either stitched or guided ad insertion at session-initialization time.

## Create a server-guided session
<a name="create-guided-session"></a>

When creating playback sessions, choose guided mode. The way to do this depends on whether your players use implicit or explicit sessions.

### Implicitly created server-guided sessions
<a name="create-implicit-guided-session"></a>

Append `aws.insertionMode=GUIDED` to the HLS multivariant playlist request. Example:

```
playback-endpoint/v1/master/hashed-account-id/origin-id/index.m3u8?aws.insertionMode=GUIDED
```

Where:
+ `playback-endpoint` is the unique playback endpoint that AWS Elemental MediaTailor generated when the configuration was created. 

  Example

  ```
  https://777788889999.mediatailor.us-east-1.amazonaws.com
  ```
+ `hashed-account-id` is your AWS account ID. 

  Example

  ```
  777788889999
  ```
+ `origin-id` is the name that you gave when creating the configuration. 

  Example

  ```
  myOrigin
  ```
+ `index.m3u8` or is the name of the manifest from the test stream plus its file extension. Define this so that you get a fully identified manifest when you append this to the video content source that you configured in [Step 4: Create a configuration](getting-started-ad-insertion.md#getting-started-add-mapping). 

Using the values from the preceding examples, the full URLs are the following.
+ Example:

  ```
  https://777788889999.mediatailor.us-east-1.amazonaws.com/v1/master/777788889999/myOrigin/index.m3u8?aws.insertionMode=GUIDED
  ```

### Explicitly created server-guided sessions
<a name="create-explicit-guided-session"></a>

Add `insertionMode=GUIDED` to JSON metadata the player sends in the HTTP `POST` to the MediaTailor configuration's session-initialization prefix endpoint.

The following example shows the structure of the JSON metadata:

```
{
  # other keys, e.g. "adsParams"
  "insertionMode": "GUIDED"       # this can be either GUIDED or STITCHED
}
```

With this initialization metadata, the playback session will use serer-guided ad insertion.

# Ad tracking with SGAI
<a name="sgai-ad-tracking"></a>

SGAI supports both server-side and client-side ad tracking. You set the reporting mode at session initialization. The mode cannot change during the session.

Server-side tracking (default)  
MediaTailor fires VAST beacons automatically when the player requests ad segments. Ad URIs in the asset list contain encrypted beacon metadata (`awsBeaconData`, `awsBeaconDomain`, `awsConfigurationName`). The player must support HLS `#EXT-X-DEFINE:QUERYPARAM` variable substitution. The asset list response does not include a `TRACKING` section.  
For details about how SGAI server-side beaconing works, see [Server-side tracking with server-guided ad insertion (SGAI)](ad-reporting-server-side-sgai.md).

Client-side tracking  
Add `aws.reportingMode=CLIENT` to your session initialization request. The asset list response includes a `TRACKING` section with beacon URLs that the player fires during ad playback. The `GetTracking` API endpoint is *not* used for SGAI sessions. Instead, each asset list response includes tracking data directly. The tracking data uses the same JSON schema as the server-side ad insertion (SSAI) tracking response.  
For details, see [Server-guided ad insertion](ad-reporting-client-side.md#ad-reporting-client-side-best-practices-sgai).

# Guided prefetch with manifest heartbeating
<a name="sgai-guided-prefetch"></a>

For live SGAI streams, you can enable manifest-based ad prefetching by adding `aws.guidedPrefetchMode=MANIFEST` to your session initialization request:

```
https://777788889999.mediatailor.us-east-1.amazonaws.com/v1/master/777788889999/myOrigin/index.m3u8?aws.insertionMode=GUIDED&aws.guidedPrefetchMode=MANIFEST
```

When enabled, MediaTailor appends a session identifier (`?aws.sessionId=<id>`) as a query parameter to each interstitial media manifest (`/v1/i-media`) URL in the multivariant playlist. Each time the player refreshes an i-media manifest, the request reaches MediaTailor with the session ID, which MediaTailor uses to enqueue prefetch requests for upcoming ad breaks.
+ The `aws.guidedPrefetchMode` parameter accepts two values: `MANIFEST` (enabled) and `OFF` (disabled, default).
+ Guided prefetch mode is only valid for SGAI sessions. Using it with stitched sessions returns an error.
+ DASH does not yet support guided prefetch mode.
+ Guided prefetch is independent of reporting mode — beacons fire at playback time, not at prefetch time.
+ **Do not cache i-media manifests in your CDN when using guided prefetch.** The prefetch mechanism depends on the player's manifest refresh requests reaching MediaTailor directly. If your CDN caches `/v1/i-media` responses, MediaTailor does not receive the heartbeat requests and cannot trigger prefetching.

# MediaTailor server-guided ad insertion feature compatibility matrix
<a name="sgai-feature-compatibility"></a>

AWS Elemental MediaTailor offers two ad insertion methods with different feature compatibility. Server-guided ad insertion works differently from server-side ad insertion, which affects compatibility with some MediaTailor features. Use this table to understand which features work with each ad insertion method.


**Feature compatibility by ad insertion method**  

| Feature | Server-side ad insertion (SSAI) | Server-guided ad insertion (SGAI) | 
| --- | --- | --- | 
| Ad prefetching | ✓ Supported | Not yet supported | 
| Ad suppression | ✓ Supported | Not applicable | 
| Pre-roll ad behavior | Controlled by MediaTailor configuration | Controlled by MediaTailor configuration | 
| Client-side ad tracking | Uses GetTracking API | Uses TRACKING section in asset list (GetTracking API is not used) | 
| Server-side ad tracking | ✓ Supported — beacons fire based on /v1/segment requests using the session ID | ✓ Supported (HLS only) — uses sessionless beaconing with encrypted beacon data embedded in ad URIs via \$1EXT-X-DEFINE:QUERYPARAM. Requires HLS v11 or later. DASH is not yet supported. | 
| Ad-ID decoration | ✓ Supported | ✗ Not compatible | 

## Compatibility details
<a name="compatibility-details"></a>

### Ad prefetching
<a name="prefetch-compatibility"></a>

Ad prefetching isn't currently supported.

### Ad suppression
<a name="prefetch-compatibility"></a>

Ad suppression isn't supported with server-guided ad insertion methods because players only fetch ads they're going to play. 

### Pre-roll ad behavior
<a name="preroll-compatibility"></a>

Pre-roll ad timing works differently between insertion methods:
+ **Server-side ad insertion:** MediaTailor controls when pre-roll ads play based on configuration settings
+ **Server-guided ad insertion:** MediaTailor inserts pre-roll ads at the top of the manifest. Your player shows these ads first, then starts your content

### Ad tracking
<a name="tracking-compatibility"></a>

**Client-side tracking** uses different mechanisms depending on the ad insertion method:
+ **Server-side ad insertion (SSAI):** Uses the `GetTracking` API endpoint
+ **Server-guided ad insertion (SGAI):** MediaTailor provides tracking information in the `TRACKING` section of each asset list response. The `GetTracking` API endpoint is not used. The session initialization response does not include a `trackingUrl`.

**Server-side tracking** also differs between methods:
+ **Server-side ad insertion (SSAI):** MediaTailor fires beacons when the player fetches stitched ad segments through `/v1/segment/` using the session ID.
+ **Server-guided ad insertion (SGAI):** MediaTailor uses sessionless beaconing. MediaTailor embeds encrypted beacon data (`awsBeaconData`, `awsBeaconDomain`, `awsConfigurationName`) in the ad manifest URIs that it returns in the asset list. The ad manifest uses `#EXT-X-DEFINE:QUERYPARAM` tags so the player substitutes these values into segment URLs. When the player requests each ad segment, MediaTailor decrypts the data, fires the appropriate beacon, and redirects to the content segment. When server-side reporting is active, MediaTailor omits the `TRACKING` section from the asset list response. For details, see [Server-side tracking with server-guided ad insertion (SGAI)](ad-reporting-server-side-sgai.md).

### Ad-ID decoration
<a name="ad-id-compatibility"></a>

Ad-ID decoration is not compatible with server-guided ad insertion because the fields that populate X-AD-CREATIVE-SIGNALING headers are only known when the asset list is fetched, not when the manifest is written.

# MediaTailor server-guided ad insertion configuration for live streams
<a name="sgai-live-configuration"></a>

AWS Elemental MediaTailor server-guided ad insertion for live content provides significant performance benefits through cacheable manifests. Configuring SGAI for live content uses the same core parameters as VOD, with specific considerations for live stream characteristics and real-time processing.

## Requirements for live SGAI
<a name="sgai-live-requirements"></a>

Before you enable SGAI for live content, ensure that you have the following:
+ Your live stream includes properly formatted DATERANGE markers
+ Ad break durations are consistent and predictable
+ Your CDN is configured to cache SGAI manifests appropriately
+ Players support server-guided ad insertion workflows
+ Your ad decision server can handle real-time requests for live content

### Player requirements
<a name="sgai-live-player-integration"></a>

Players must be configured to handle SGAI live manifests properly:
+ Support for server-guided ad insertion workflows
+ Ability to process ad insertion guidance from manifests
+ Proper handling of live stream timing and synchronization
+ For HLS content: Support for HLS version 8 and EXT-X-DATERANGE with CLASS attribute. Version 11 for server-side beaconing.
+ For HLS content: EXT-X-DEFINE variable substitution support

## Live playback configuration
<a name="sgai-live-playback-config"></a>

To enable SGAI for live content, create a playback configuration that has the following settings:

**Example SGAI live playback configuration**  

```
{
  "Name": "LiveSGAIConfig",
  "VideoContentSourceUrl": "https://your-live-origin.com/live/stream.m3u8",
  "AdDecisionServerUrl": "https://your-ads.com/ads",
  "PersonalizationThresholdSeconds": 1,
  "InsertionMode": "PLAYER_SELECT"
}
```

The following are key considerations for live SGAI configuration:

`VideoContentSourceUrl`  
Must point to a live HLS stream with properly formatted SCTE-35 DATERANGE markers. The stream should maintain consistent segment durations and bitrate variants.

## SGAI live manifest requests
<a name="sgai-live-manifest-requests"></a>

SGAI live manifests use the same URL pattern as traditional ad insertion:

```
https://your-config.mediatailor.region.amazonaws.com/v1/master/config-name/manifest.m3u8?aws.insertionMode=GUIDED
```

## Manifest-based prefetch for live SGAI
<a name="sgai-live-guided-prefetch"></a>

For live SGAI workflows, you can enable manifest-based prefetch heartbeating to reduce ad fill latency. Add `aws.guidedPrefetchMode=MANIFEST` to the manifest request:

```
https://your-config.mediatailor.region.amazonaws.com/v1/master/config-name/manifest.m3u8?aws.insertionMode=GUIDED&aws.guidedPrefetchMode=MANIFEST
```

When enabled, MediaTailor appends a session identifier (`?aws.sessionId=<id>`) as a query parameter to each interstitial media manifest (`/v1/i-media`) URL in the multivariant playlist. Each time the player refreshes an i-media manifest, the request reaches MediaTailor with the session ID, which MediaTailor uses to identify the session and enqueue prefetch requests for upcoming ad breaks.

**Important**  
**Do not cache i-media manifests in your CDN when using guided prefetch.** The prefetch heartbeating mechanism depends on the player's manifest refresh requests reaching MediaTailor directly. If your CDN caches and serves `/v1/i-media` responses, MediaTailor does not receive the heartbeat requests and cannot trigger prefetching. Configure your CDN to pass through `/v1/i-media/*` requests to MediaTailor when `aws.guidedPrefetchMode=MANIFEST` is in use.

Guided prefetch is independent of the reporting mode. Whether you use server-side (default) or client-side (`aws.reportingMode=CLIENT`) tracking, beacons fire at playback time, not when ads are prefetched. For general information about how ad prefetching works in MediaTailor, see [Prefetching ads](prefetching-ads.md).

## Testing SGAI live configuration
<a name="sgai-live-testing"></a>

Verify your SGAI live setup with these validation steps:

1. **Test manifest generation**

   Request the SGAI live manifest URL and verify it returns cacheable content with proper ad insertion guidance.

1. **Verify CDN caching**

   Check that your CDN is caching SGAI manifests according to the configured TTL values.

1. **Test ad insertion**

   Confirm that players can successfully insert ads using the guidance provided in SGAI manifests.

1. **Monitor performance**

   Use CloudWatch metrics to verify reduced origin load and improved cache hit rates.

# MediaTailor server-guided ad insertion configuration for VOD content
<a name="sgai-vod-configuration"></a>

AWS Elemental MediaTailor server-guided ad insertion for VOD content provides significant performance benefits through highly cacheable manifests and reduced server processing. Configuring SGAI for VOD content leverages the static nature of video-on-demand assets to maximize caching efficiency and minimize origin requests, making it ideal for large content libraries with repeated viewing patterns.

## Requirements for VOD SGAI
<a name="sgai-vod-requirements"></a>

Before you enable SGAI for VOD content, ensure that you have the following:
+ Your VOD content includes properly formatted ad markers (SCTE-35 or timed metadata)
+ Content is stored in a reliable origin with consistent availability
+ Your CDN is configured to cache SGAI manifests with appropriate TTL values
+ Players support server-guided ad insertion workflows
+ Your ad decision server can handle VOD-specific metadata and targeting

### Player requirements
<a name="sgai-vod-player-requirements"></a>

Players must be configured to handle SGAI VOD manifests and ad insertion:
+ Support for server-guided ad insertion workflows
+ Ability to process ad insertion guidance from VOD manifests
+ Support for client-side ad insertion during VOD playback
+ Proper handling of seek operations across ad breaks
+ Support for content duration and position tracking

## VOD playback configuration
<a name="sgai-vod-playback-config"></a>

To enable SGAI for VOD content, create a playback configuration that has the following settings:

**Example SGAI VOD playback configuration**  

```
{
  "Name": "VODSGAIConfig",
  "VideoContentSourceUrl": "https://your-vod-origin.com/content/",
  "AdDecisionServerUrl": "https://your-ads.com/ads",
  "PersonalizationThresholdSeconds": 5,
  "InsertionMode": "PLAYER_SELECT"
}
```

The following are key considerations for VOD SGAI configuration:

`VideoContentSourceUrl`  
Should point to your VOD content library with consistent URL patterns. Ensure the origin can handle the expected request volume and provides reliable content delivery.

`ConfigurationAliases`  
Include VOD-specific parameters like content duration, genre, or series information that can be used for ad targeting without affecting manifest cacheability.

`ManifestProcessingRules`  
Enable ad marker passthrough to preserve original content timing information, which is especially important for VOD content with pre-defined ad break positions.

## SGAI VOD manifest requests
<a name="sgai-vod-manifest-requests"></a>

SGAI VOD manifests use the same URL pattern traditional VOD ad insertion. 

```
https://your-config.mediatailor.region.amazonaws.com/v1/master/config-name/content-path/manifest.m3u8?aws.insertionMode=GUIDED
```

## VOD-specific ad targeting
<a name="sgai-vod-ad-targeting"></a>

VOD content enables unique ad targeting opportunities:

### Content metadata targeting
<a name="sgai-vod-content-metadata"></a>

Leverage VOD content metadata for improved ad targeting:
+ **Genre and category:** Target ads based on content type (drama, comedy, documentary)
+ **Content rating:** Ensure age-appropriate ad content (G, PG, R ratings)
+ **Series and season:** Target ads for series continuity or related content
+ **Release date:** Target based on content age (new releases vs. catalog content)
+ **Content duration:** Adjust ad load based on total content length

### Viewing context targeting
<a name="sgai-vod-viewing-context"></a>

VOD viewing patterns enable contextual ad targeting:
+ **Time of day:** Target ads based on when content is being watched
+ **Binge watching:** Adjust ad frequency for users watching multiple episodes
+ **Completion rate:** Target based on user's historical content completion patterns
+ **Device type:** Optimize ad formats for viewing device (TV, mobile, tablet)

## Testing SGAI VOD configuration
<a name="sgai-vod-testing"></a>

Verify your SGAI VOD setup with these validation steps:

1. **Test manifest generation**

   Request SGAI VOD manifest URLs for different content types and verify they return cacheable content with proper ad insertion guidance.

1. **Verify CDN caching**

   Check that your CDN is caching SGAI manifests according to the configured TTL values and achieving high cache hit rates.

1. **Test ad insertion**

   Confirm that players can successfully insert ads using the guidance provided in SGAI manifests for various VOD content.

1. **Test seek operations**

   Verify that seeking within VOD content works correctly across ad breaks and maintains proper playback position.

1. **Monitor performance**

   Use CloudWatch metrics to verify reduced origin load, improved cache hit rates, and successful ad insertion rates.

### Key testing scenarios
<a name="sgai-vod-testing-scenarios"></a>

Test these specific VOD scenarios:
+ **Popular content:** Verify high cache hit rates for frequently accessed VOD assets
+ **Long-form content:** Test ad insertion in movies or long episodes with multiple ad breaks
+ **Series content:** Verify consistent ad targeting across episodes in a series
+ **Different genres:** Test ad targeting based on content metadata and genre

## VOD SGAI optimization best practices
<a name="sgai-vod-optimization"></a>

Optimize your SGAI VOD implementation for maximum performance:

### Cache optimization
<a name="sgai-vod-cache-optimization"></a>
+ **Maximize TTL values:** Use longer cache durations for VOD manifests since content doesn't change
+ **Minimize cache keys:** Reduce cache key variations to improve hit rates
+ **Pre-warm popular content:** Cache manifests for trending or featured VOD content
+ **Monitor cache performance:** Track cache hit rates and optimize based on usage patterns

### Content delivery optimization
<a name="sgai-vod-content-optimization"></a>
+ **Consistent URL patterns:** Use predictable URL structures for better caching
+ **Metadata standardization:** Ensure consistent content metadata for reliable ad targeting
+ **Ad break positioning:** Optimize ad break placement for natural content transitions
+ **Quality variants:** Ensure SGAI works across all bitrate variants of your VOD content

# MediaTailor ad server integration requirements
<a name="vast"></a>

To integrate your ad server with AWS Elemental MediaTailor, your ad server must send XML that conforms to the IAB specifications for the supported versions of VAST and VMAP. You can use a public VAST validator to ensure that your tags are well-formed.

AWS Elemental MediaTailor supports VAST and VMAP responses from ad decision servers. AWS Elemental MediaTailor also supports the proxying of VPAID metadata through our client-side reporting API for client-side ad insertion. For information about client-side reporting, see [Client-side ad tracking](ad-reporting-client-side.md).

MediaTailor supports the following versions of VAST, VMAP, and VPAID:
+ Up to [VAST 4.3](https://iabtechlab.com/standards/vast/) 

  MediaTailor accepts response versions through VAST 4.3, but some advanced features from VAST 4.0 and up are not be supported.
+ [VMAP 1.0](https://www.iab.com/guidelines/digital-video-multiple-ad-playlist-vmap-1-0-1/)
+ [VPAID 2.0](https://www.iab.com/guidelines/digital-video-player-ad-interface-definition-vpaid-2-0/)

## VAST requirements
<a name="vast-integration"></a>

Your ad server's VAST response must contain IAB compliant `TrackingEvents` elements and standard event types, like `impression`. If you include non-standard tracking events, AWS Elemental MediaTailor rejects the VAST response and doesn't provide an ad for the avail.

VAST 3.0 introduced support for ad pods, which is the delivery of a set of sequential linear ads. If a specific ad in an ad pod is not available, AWS Elemental MediaTailor logs an error on CloudWatch, in the interactions log of the ADS. It then tries to insert the next ad in the pod. In this way, MediaTailor iterates through the ads in the pod until it finds one that it can use.

### Targeting
<a name="targeting"></a>

To target specific players for your ads, you can create templates for your ad tags and URLs. For more information, see [MediaTailor dynamic ad variables for ADS requests](variables.md).

AWS Elemental MediaTailor proxies the player's `user-agent` and `x-forwarded-for` headers when it sends the ad server VAST request and when it makes the server-side tracking calls. Make sure that your ad server can handle these headers. Alternatively, you can use `[session.user_agent]` or `[session.client_ip]` and pass these values in query strings on the ad tag and ad URL. For more information, see [MediaTailor session variables for ADS requests](variables-session.md).

### Ad calls
<a name="ad-calls"></a>

AWS Elemental MediaTailor calls your VAST ads URL as defined in your configuration. It substitutes any player-specific or session-specific parameters when making the ad call. MediaTailor follows up to seven levels of VAST wrappers and redirects in the VAST response. In live streaming scenarios, MediaTailor makes ad calls simultaneously at the ad avail start for connected players. In practice, due to jitter, these ad calls can be spread out over a few seconds. Make sure that your ad server can handle the number of concurrent connections this type of calling requires. MediaTailor supports prefetching VAST responses for live workflows. For more information, see [Prefetching ads](prefetching-ads.md).

### Creative handling
<a name="creative-handling"></a>

When AWS Elemental MediaTailor receives the ADS VAST response, for each creative it identifies the highest bitrate `MediaFile` for transcoding and uses this as its source. It sends this file to the on-the-fly transcoder for transformation into renditions that fit the player's multivariant playlist bitrates and resolutions. For best results, make sure that your highest bitrate media file is a high-quality MP4 asset with valid manifest presets. When manifest presets aren't valid, the transcode jobs fail, resulting in no ad shown. Examples of presets that aren't valid include unsupported input file formats, like ProRes, and certain rendition specifications, like the resolution 855X481. 

For a list of supported formats for media file inputs, see the **MP4** row of [Supported input formats](https://docs.aws.amazon.com/mediaconvert/latest/ug/reference-codecs-containers-input.html) in the *AWS Elemental MediaConvert User Guide*.

**Creative indexing**  
AWS Elemental MediaTailor uniquely indexes each creative by the value of the `id` attribute provided in the `<Creative>` element. If a creative's ID is not specified, MediaTailor uses the media file URL for the index.

The following example declaration shows the creative ID.

```
<Creatives>
        <Creative id="57859154776" sequence="1">
```

If you define your own creative IDs, use a new, unique ID for each creative. Don't reuse creative IDs. AWS Elemental MediaTailor stores creative content for repeated use, and finds each by its indexed ID. When a new creative comes in, the service first checks its ID against the index. If the ID is present, MediaTailor uses the stored content, rather than reprocessing the incoming content. If you reuse a creative ID, MediaTailor uses the older, stored ad and doesn't play your new ad. 

**VAST extensions provided by ad-serving partners**  
To help prevent collisions with creative IDs, you can use extensions provided by ad-serving partners for the VAST response. MediaTailor supports extensions from SpringServe, Publica, and FreeWheel. When you enable VAST extension overrides, MediaTailor replaces the default creative ID with the extension value.

To enable this feature, [submit an AWS Support ticket](https://console.aws.amazon.com/support/home#/) to request VAST extension-based creative IDs to be enabled. Include the following information in the Support ticket:
+ AWS Region
+ AWS account ID
+ MediaTailor playback configuration names

To validate that VAST extension-based creative IDs are enabled on your account, we recommend that you also request `RAW_ADS_RESPONSE` logging to be enabled on a staging or testing playback configuration. With logging, you can view the original VAST response that the ADS receives and confirm that the correct creative IDs are used. 

## VPAID requirements
<a name="vpaid"></a>

VPAID allows publishers to serve highly interactive video ads and to provide viewability metrics on their monetized streams. For information about VPAID, see the [VPAID specification](https://www.iab.com/guidelines/digital-video-player-ad-interface-definition-vpaid-2-0/).

AWS Elemental MediaTailor supports a mix of server-side-stitched VAST MP4 linear ads and client-side-inserted VPAID interactive creatives in the same ad avail. It preserves the order in which they appear in the VAST response. MediaTailor follows VPAID redirects through a maximum of seven levels of wrappers. The client-side reporting response includes the unwrapped VPAID metadata.

To use VPAID, follow these guidelines:
+ Configure an MP4 slate for your VPAID creatives. AWS Elemental MediaTailor fills the VPAID ad slots with your configured slate, and provides VPAID ad metadata for the client player to use to run the interactive ads. If you don't have a slate configured, when a VPAID ad appears, MediaTailor provides the ad metadata through client-side reporting as usual. It also logs an error in CloudWatch about the missing slate. For more information, see [MediaTailor slate ad insertion](slate-management.md) and [Creating an MediaTailor playback configuration](configurations-create.md). 
+ Use client-side reporting. AWS Elemental MediaTailor supports VPAID through our client-side reporting API. For more information, see [Client-side ad tracking](ad-reporting-client-side.md). 

  It is theoretically possible to use the default server-side reporting mode with VPAID. However, if you use server-side reporting, you lose any information about the presence of the VPAID ad and the metadata surrounding it, because that is available only through the client-side API. 
+ In live scenarios, make sure that your ad avails, denoted by `EXT-X-CUE-OUT: Duration`, are long enough to accommodate any user interactivity on VPAID. For example, if the VAST XML specifies a VPAID ad that is 30 seconds long, consider configuring your ad avail to be more than 30 seconds. This additional time gives users more chance to interact with the ad. If you don't add time, you could lose the VPAID metadata because the remaining duration in the ad avail is not long enough to accommodate the VPAID ad.



# MediaTailor playback configuration management
<a name="working-with-configurations"></a>

This section covers the key tasks for managing AWS Elemental MediaTailor playback configurations. You can learn how to create a new configuration to set up content streams and provide access for playback devices, view details of an existing configuration, edit a configuration to update settings like origin servers and ad decision servers, and delete a configuration that is no longer needed.

**Topics**
+ [Creating an MediaTailor playback configuration](configurations-create.md)
+ [Viewing MediaTailor configuration details](configurations-view.md)
+ [Editing MediaTailor configuration settings](configurations-edit.md)
+ [Deleting MediaTailor configurations](configurations-delete.md)

# Creating an MediaTailor playback configuration
<a name="configurations-create"></a>

This topic shows how to create a configuration to start receiving content streams with AWS Elemental MediaTailor. It also shows how to provide an access point for downstream playback devices to request content.

You can use the AWS Elemental MediaTailor console, the AWS Command Line Interface (AWS CLI)>, or the MediaTailor API to create a configuration. For information about creating a configuration through the AWS CLI or MediaTailor API, see the [https://docs.aws.amazon.com/mediatailor/latest/apireference/what-is.html](https://docs.aws.amazon.com/mediatailor/latest/apireference/what-is.html)..

When you create a configuration, don't put sensitive identifying information into free-form fields such as the **Configuration name** field. Identifying information can include things like customer account numbers. In addition, don't use identifying information when you work in the MediaTailor console, REST API, the AWS CLI, or AWS SDKs. Any data that you enter into MediaTailor might get picked up for inclusion in diagnostic logs or Amazon CloudWatch Events.

**To add a configuration (console)**

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

1. On the **Configurations** page, choose **Create configuration**. 

1. Complete the configuration and additional configuration fields as described in the following topics:
   +  [Required settings](#configurations-create-main) 
   +  [Optional configuration settings](#configurations-create-addl) 

1. Choose **Create configuration**. 

   AWS Elemental MediaTailor displays the new configuration in the table on the **Configurations** page.

1. (Recommended) Set up a CDN with AWS Elemental MediaTailor for manifest and reporting requests. You can use the configuration playback URLs for the CDN setup. For information about setting up a CDN for manifest and reporting requests, see [Using a CDN to optimize MediaTailor ad personalization and content delivery](integrating-cdn.md).

## Required settings
<a name="configurations-create-main"></a>

When you create a configuration, you must include the following required settings.

**Name**  
Enter a unique name that describes the configuration. The name is the primary identifier for the configuration. The maximum length allowed is 512 characters.

**Content source**  
 Enter the URL prefix for the manifest for this stream, minus the asset ID. The maximum length is 512 characters.  
For example, the URL prefix `http://origin-server.com/a/` is valid for an HLS multivariant playlist URL of `http://origin-server.com/a/main.m3u8` and for a DASH MPD URL of `http://origin-server.com/a/dash.mpd`. Alternatively, you can enter a shorter prefix such as `http://origin-server.com`, but the `/a/` must be included in the asset ID in the player request for content.   
If your content origin uses HTTPS, its certificate must be from a well-known certificate authority. It can't be a self-signed certificate. If you use a self-signed certificate, AWS Elemental MediaTailor fails to connect to the content origin and can't serve manifests in response to player requests.

**Ad decision server**  
 Enter the URL for your ad decision server (ADS). This is either the URL with variables as described in [Step 3: Configure ADS request URL and query parameters](getting-started-ad-insertion.md#getting-started-configure-request) , or the static VAST URL that you are using for testing purposes. The maximum length is 25,000 characters.  
If your ADS uses HTTPS, its certificate must be from a well-known certificate authority. It can't be a self-signed certificate. The same also applies to mezzanine ad URLs returned by the ADS. If you use a self-signed certificate, then AWS Elemental MediaTailor can't retrieve and stitch ads into the manifests from the content origin.

## Optional configuration settings
<a name="configurations-create-addl"></a>

You can optionally configure ** configuration aliases**, ** personalization details**, and **advanced settings** in the MediaTailor console, MediaTailor API, or the AWS Command Line Interface (AWS CLI).

### Configuration aliases
<a name="configurations-configuration-aliases"></a>

The following are optional configuration aliases that you can configure in the MediaTailor console, or with the MediaTailor API.

**Player parameter variable**  
For dynamic domain configuration during session initialization, add one or more player parameter variables.  
For more information about using player parameter variables to dynamically configure domains, see [MediaTailor domain variables for multiple content sources](variables-domains.md).

### Log configuration
<a name="configurations-log-configurations"></a>

The following are log configuration settings.

**Percent enabled**  
Sets the percentage of playback configuration session logs that MediaTailor writes to CloudWatch Logs. For example, if your playback configuration has 1000 sessions, and you set percent enabled to **60**, MediaTailor writes 600 session logs to CloudWatch Logs.  
 When you enable this option, MediaTailor automatically creates a service-linked role that allows MediaTailor to write and manage session logs in your CloudWatch Logs account. For more information, see [Using service-linked roles for MediaTailor](using-service-linked-roles.md). 

**Logging strategies**  
Indicates the method used for collecting logs that MediaTailor emits. To send logs directly to CloudWatch Logs, choose `LEGACY_CLOUDWATCH`. To send logs to CloudWatch Logs, which then vends logs to your destination of choice, choose `VENDED_LOGS`. Supported destinations are a CloudWatch Logs log group, Amazon S3 bucket, and Amazon Data Firehose stream.  
Additional set up is required for vended logs. For set up, see [Using vended logs](vended-logs.md).

**ADS interaction log opt-in events**  
Indicates that MediaTailor will emit `RAW_ADS_RESPONSE` logs for sessions that are initialized with this configuration.   
The `RAW_ADS_RESPONSE` log event contains the entire VAST or VMAP response from the ADS. As such, the logs can be extensive and might increase your logging costs.

**ADS interaction log exclude events**  
Indicates that MediaTailor won't emit the selected events in the logs that describe interactions with the ADS.  
For a description of ADS log events, see [ADS logs](ads-log-format.md).

**Manifest service interaction log exclude events**  
Indicates that MediaTailor won't emit the selected events in the logs that describe interactions with the manifest service.  
For a description of manifest service log events, see [Manifest logs](log-types.md).

### Ad conditioning
<a name="configurations-ad-conditioning"></a>

The following determine what actions MediaTailor takes to condition ads before stitching them into a content stream. 

**Streaming media file conditioning**  
Determines the logic that MediaTailor uses when deciding which ads to stitch.   
+ When **Streaming media file conditioning** is set to **Transcode**, MediaTailor transcodes the media files with `progressive` delivery and stitches them into the manifest. If there aren't enough ads with `progressive` delivery media files to fill the avail, MediaTailor transcodes and uses those with `streaming` delivery.
+ When **Streaming media file conditioning** is set to **None**, MediaTailor stitches ads with `streaming` delivery media files into the manifest without transcoding them. If there aren't enough ads with `streaming` delivery media files to fill the avail, MediaTailor transcodes and uses those with `progressive` delivery. 

### Personalization details
<a name="configurations-personalization-details"></a>

The following are personalization details that you can configure in the MediaTailor console or with the MediaTailor API.

**Slate ad**  
Enter the URL for a high-quality MP4 asset that MediaTailor uses to fill unfilled ad time. Slate configuration is optional for most workflows but mandatory for VPAID ads. For comprehensive information about slate behavior, configuration requirements, and when slate is shown, see [MediaTailor slate ad insertion](slate-management.md).

**Start bumper**  
The URL of the start bumper asset location. Bumpers are short video or audio clips that play at the beginning or end of an ad break. They can be stored on Amazon's S3, or a different storage service. To learn more about bumpers, see [MediaTailor bumper ad insertion](bumpers.md).

**End bumper**  
The URL of the end bumper asset location. Bumpers are short video or audio clips that play at the beginning or end of an ad break. They can be stored on Amazon's S3, or a different storage service. To learn more about bumpers, see [MediaTailor bumper ad insertion](bumpers.md).

**Personalization threshold**  
Only applies when used in conjunction with slate ad. Defines the maximum duration of underfilled ad time (in seconds) allowed in an ad break before MediaTailor abandons personalization and shows underlying content. This feature applies to ad replacement in live and VOD streams, rather than ad insertion, because it relies on an underlying content stream. For detailed behavior scenarios and comprehensive information, see [How personalization threshold works](slate-management.md#personalization-threshold-scenarios).

**Live pre-roll ad decision server**  
To insert ads at the start of a live stream before the main content starts playback, enter the URL for the ad pre-roll from the ad decision server (ADS). This is either the URL with variables as described in [Step 3: Configure ADS request URL and query parameters](getting-started-ad-insertion.md#getting-started-configure-request), or the static VAST URL that you are using for testing purposes. The maximum length is 25,000 characters.  
If your ADS uses HTTPS, its certificate must be from a well-known certificate authority. It can't be a self-signed certificate. The same also applies to mezzanine ad URLs returned by the ADS. If you use a self-signed certificate, then AWS Elemental MediaTailor can't retrieve and stitch ads into the manifests from the content origin.
For information about how pre-roll works, see [MediaTailor pre-roll ad insertion](ad-behavior-preroll.md).

**Live pre-roll maximum allowed duration**  
When you're inserting ads at the start of a live stream, enter the maximum allowed duration for the pre-roll ad avail. MediaTailor won't go over this duration when inserting ads. If the response from the ADS contains more ads than will fit in this duration, MediaTailor fills the avail with as many ads as possible, without going over the duration. For more details about how MediaTailor fills avails, see [Live ad stitching behavior](ad-behavior.md#ad-behavior-live) .

**Avail suppression mode**  
Sets the mode for avail suppression, also known as ad suppression. By default, ad suppression is off and MediaTailor fills all with ads or slate. When the mode is set to `BEHIND_LIVE_EDGE`, ad suppression is active and MediaTailor doesn't fill ad breaks on or behind the avail suppression value time in the manifest lookback window. When the mode is set to `AFTER_LIVE_EDGE`, ad suppression is active. MediaTailor doesn't fill ad breaks on or behind the avail suppression period, which is the live edge plus the avail suppression value plus buffer time.

**Avail suppression value**  
The avail suppression value is a live edge offset time in `HH:MM:SS`. MediaTailor won't fill ad breaks on or behind this time in the manifest lookback window.

**Insertion Mode**  
Insertion Mode controls whether players can use stitched or guided ad insertion. The default, `STITCHED_ONLY`, forces all player sessions to use stitched (server-side) ad insertion. Setting InsertionMode to `PLAYER_SELECT` allows players to select either stitched or guided ad insertion at session-initialization time. The default for players that do not specify an insertion mode is stitched.

### Advanced settings
<a name="configurations-advanced-settings"></a>

The following are optional settings are advanced. You can configure these in the MediaTailor console, with the AWS Command Line Interface (AWS CLI), or using the MediaTailor API.

**CDN content segment prefix**  
Enables AWS Elemental MediaTailor to create manifests with URLs to your CDN path for content segments. Before you do this step, set up a rule in your CDN to pull segments from your origin server. For **CDN content segment prefix**, enter the CDN prefix path.  
For more information about integrating MediaTailor with a CDN, see [Using a CDN to optimize MediaTailor ad personalization and content delivery](integrating-cdn.md).

**CDN ad segment prefix**  
Enables AWS Elemental MediaTailor to create manifests with URLs to your own CDN path for ad segments. By default, MediaTailor serves ad segments from an internal Amazon CloudFront distribution with default cache settings. Before you can complete the **CDN ad segment prefix** field, you must set up a rule in your CDN to pull ad segments from the following origin, like in the following example.  

```
https://segments.mediatailor.<region>.amazonaws.com
```
For **CDN ad segment prefix**, enter the name of your CDN prefix in the configuration.  
For more information about integrating MediaTailor with a CDN, see [Using a CDN to optimize MediaTailor ad personalization and content delivery](integrating-cdn.md).

**DASH origin manifest type**  
If your origin server produces single-period DASH manifests, open the dropdown list and choose **SINGLE\$1PERIOD**. By default, MediaTailor handles DASH manifests as multi-period manifests. For more information, see [Integrating an MPEG-DASH source](manifest-dash.md).

**DASH mpd location**  
(Optional as needed for DASH) The media presentation description (mpd) location. Choose **DISABLED** for the following situation:  
+ You set up CDN routing rules for accessing MediaTailor manifests.
+ You use client-side reporting, or your player supports sticky HTTP redirects.
For more information about the **Location** feature, see [DASH location feature](dash-location-feature.md).

**Transcode profile name**  
The name that associates this configuration with a custom transcode profile. This name overrides the dynamic transcoding defaults of MediaTailor. Complete this field only if you have already set-up custom profiles with the help of AWS Support.

**Ad marker passthrough**  
For HLS, enables or disables ad marker passthrough. When ad marker passthrough is enabled, MediaTailor passes through `EXT-X-CUE-IN`, `EXT-X-CUE-OUT`, and `EXT-X-SPLICEPOINT-SCTE35` ad markers from the origin manifest to the MediaTailor personalized manifest. No logic is applied to the ad marker values; they are passed from the origin manifest to the personalized manifest as-is. For example, if `EXT-X-CUE-OUT` has a value of `60` in the origin manifest, but no ads are placed, MediaTailor won't change the value to `0` in the personalized manifest.

# Viewing MediaTailor configuration details
<a name="configurations-view"></a>

In addition to the values provided when the configuration was created, AWS Elemental MediaTailor displays the name of the configuration, playback endpoints, and relevant access URLs. To view a configuration, use the following procedure.



 **To view a configuration ** 

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

1. On the **Configurations** page, choose the **Configuration name** for the configuration to view.

# Editing MediaTailor configuration settings
<a name="configurations-edit"></a>

You can edit a configuration to update the origin server and ad decision server (ADS) mapping, or change how AWS Elemental MediaTailor interacts with a content distribution network (CDN).



 **To edit a configuration ** 

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

1. On the **Configurations** page, choose the name of the configuration that you want to edit.

1. On the configuration details page, choose **Edit**, and then revise the configuration settings as needed. You can't edit the configuration name. For information about configuration attributes, see [Creating an MediaTailor playback configuration](configurations-create.md).

1. Choose **Save**. 

# Deleting MediaTailor configurations
<a name="configurations-delete"></a>

You can delete a configuration to make it unavailable for playback with AWS Elemental MediaTailor.



 **To delete a configuration ** 

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

1. On the **Configurations** page, do one of the following:
   + Choose the name of the configuration that you want to delete. 
   + In the **Configuration name** column, choose the option next to the name, and then choose **Delete**. 

1. In the **Delete** confirmation box, enter **Delete**, and then choose **Delete**. 

# Integrating a content source for MediaTailor ad insertion
<a name="integrating-origin"></a>

This topic covers integrating different types of video content sources with MediaTailor. MediaTailor supports both HLS and DASH streaming protocols for live and on-demand content. The service can perform ad insertion or replacement during designated ad breaks, and has specific requirements for the structure and formatting of the input video manifests to enable these capabilities. The following topics provide details on the input source requirements and steps for integrating HLS and DASH content with MediaTailor to enable personalized ad experiences.

**Topics**
+ [Input source requirements for MediaTailor ad insertion](stream-reqmts.md)
+ [Integrating an HLS source](manifest-hls.md)
+ [Integrating an MPEG-DASH source](manifest-dash.md)
+ [Securing AWS Elemental MediaTailor origin interactions with SigV4](origin-sigv4.md)

# Input source requirements for MediaTailor ad insertion
<a name="stream-reqmts"></a>

A input source must meet the following requirements to work with MediaTailor:
+ Use Apple HLS (HTTP Live Streaming) or MPEG DASH (Dynamic Adaptive Streaming over HTTP)
+ Use live streaming or video on demand (VOD)
+ Be accessible on the public internet and have a public IP address
+ Use standard HTTP ports (port 80) or HTTPS ports (port 443). MediaTailor does not support custom ports for origin server communication.
+ Contain ad markers in one of the formats described in the [Getting started with MediaTailor ad insertion tutorial](getting-started-ad-insertion.md#getting-started-prep-stream) 

# Integrating an HLS source
<a name="manifest-hls"></a>

AWS Elemental MediaTailor supports `.m3u8` HLS manifests with an `EXT-X-VERSION` of `3` or higher for live streaming and video on demand (VOD). When MediaTailor encounters an ad break, it attempts ad insertion or replacement, based on the type of content. If there aren't enough ads to fill the duration, for the remainder of the ad break, MediaTailor displays the underlying content stream or the configured slate. For more information about HLS ad behavior based on content type, see [Understanding AWS Elemental MediaTailor ad insertion behavior](ad-behavior.md).

The following sections provide more information about how MediaTailor handles HLS manifests.

**Topics**
+ [HLS supported ad markers](hls-ad-markers.md)
+ [Enabling ad marker passthrough](ad-marker-passthrough.md)
+ [HLS manifest tag handling](manifest-hls-tags.md)
+ [HLS manifest examples](manifest-hls-example.md)

# HLS supported ad markers
<a name="hls-ad-markers"></a>

AWS Elemental MediaTailor identifies ad avail boundaries in an HLS manifest by parsing the input manifest for supported ad markers. The following sections describe what markers MediaTailor uses.

## EXT-X-ASSET
<a name="hls-ad-markers-asset"></a>

The `EXT-X-ASSET` tag contains metadata that's used by the ad decision server (ADS) to personalize content for the viewer. `EXT-X-ASSET` parameters are comma-separated key-value pairs.

To use this tag, you must meet the following requirements:
+ You must URL-encode the `EXT-X-ASSET` *values* in the origin manifest. The following example shows the `EXT-X-ASSET` tag with keys and URL-encoded values.

  ```
              #EXT-X-ASSET:GENRE=CV,CAID=12345678,EPISODE="Episode%20Name%20Date",SEASON="Season%20Name%20and%20Number",SERIES="Series%2520Name"
  ```
+ You must include the dynamic `[asset.]` variable and the *keys* in your MediaTailor ADS configuration. The following example shows an MediaTailor ADS configuration using the dynamic `[asset.]` variable and keys.

  ```
              https://myads.com/stub?c=[asset.GENRE]&g=[asset.CAID]&e=[asset.EPISODE]&s=[asset.SEASON]&k=[asset.SERIES]
  ```

**Example VAST request**  
The following example shows a VAST `GET` request to an ADS.

```
            https://myads.com/stub?c=CV&g=12345678&e=Episode%20Name%20Date&s=Season%20Name%20and%20Number&k=Series%2520Name
```

## EXT-X-CUE-OUT and EXT-X-CUE-IN
<a name="hls-ad-markers-cue"></a>

This type of ad marker is the most common. The following examples show options for these cue markers.

```
#EXT-X-CUE-OUT:DURATION=120
    ...
    #EXT-X-CUE-IN
```

```
#EXT-X-CUE-OUT:30.000
    ...
    #EXT-X-CUE-IN
```

```
#EXT-X-CUE-OUT
    ...
    #EXT-X-CUE-IN
```

## EXT-X-DATERANGE
<a name="hls-ad-markers-range"></a>

With `EXT-X-DATERANGE` ad marker tags, you use `SCTE35-OUT` attributes to specify the timing of the ad avail. 

**Note**  
AWS Elemental MediaTailor ignores any `START-DATE` attributes that are provided for `EXT-X-DATERANGE` ad markers. 

You can specify the ad avail in one of the following ways:
+ `EXT-X-DATERANGE` tag with `SCTE35-OUT` and `DURATION` specifications. 

  Example

  ```
  #EXT-X-DATERANGE:ID="splice-6FFFFFF0",START-DATE="2019-01T00:15:00Z\",DURATION=60.000,SCTE35-OUT=0xF
  ```
+ Paired `EXT-X-DATERANGE` tags, the first with a `SCTE35-OUT` specification and the second with a `SCTE35-IN` specification. 

  Example

  ```
  #EXT-X-DATERANGE:ID="splice-6FFFFFF0",START-DATE="2019-01T00:15:00Z\",SCTE35-OUT=0xF
      ...
      #EXT-X-DATERANGE:ID="splice-6FFFFFF0",START-DATE="2019-01T00:15:00Z\",SCTE35-IN=0xF
  ```
+ A combination of the prior options. You specify an `EXT-X-DATERANGE` tag with `SCTE35-OUT` and `DURATION` specifications followed by an `EXT-X-DATERANGE` tag with a `SCTE35-IN` specification. In this case, MediaTailor uses the earliest cue-in setting from the two specifications.

  Example

  ```
  #EXT-X-DATERANGE:ID="splice-6FFFFFF0",START-DATE="2019-01T00:15:00Z\",DURATION=60.000,SCTE35-OUT=0xF
      ...
      #EXT-X-DATERANGE:ID="splice-6FFFFFF0",START-DATE="2019-01T00:15:00Z\",SCTE35-IN=0xF
  ```

## EXT-X-SPLICEPOINT-SCTE35
<a name="hls-ad-markers-splice"></a>

You append the `EXT-X-SPLICEPOINT-SCTE35` ad marker tag with a SCTE-35 payload in base64-encoded binary. The decoded binary must provide a SCTE-35 `splice_info_section` containing the cue-out marker `0x34`, for provider placement opportunity start, and the cue-in marker `0x35`, for provider placement opportunity end. 

The following example shows the splice point specification with base64-encoded binary payloads that specify the cue-out and cue-in markers. 

```
    #EXT-X-SPLICEPOINT-SCTE35:/DA9AAAAAAAAAP/wBQb+uYbZqwAnAiVDVUVJAAAKqX//AAEjW4AMEU1EU05CMDAxMTMyMjE5M19ONAAAmXz5JA==
    ...
    #EXT-X-SPLICEPOINT-SCTE35:/DA4AAAAAAAAAP/wBQb+tTeaawAiAiBDVUVJAAAKqH+/DBFNRFNOQjAwMTEzMjIxOTJfTjUAAIiGK1s=
```

# Enabling ad marker passthrough
<a name="ad-marker-passthrough"></a>

By default for HLS, MediaTailor personalized manifests don't include the SCTE-35 ad markers from the origin manifests. When ad marker passthrough is enabled, MediaTailor passes through the following ad markers from origin manifests into personalized manifests:
+ EXT-X-CUE-IN
+ EXT-X-CUE-OUT
+ EXT-X-SPLICEPOINT-SCTE35

 Ad marker passthrough is an optional setting. Use ad marker passthrough if you want the SCTE ad markers to be included in the MediaTailor personalized manifest. Common use cases include the following: 
+ Content replacement - Perform content replacement or content restriction.
+ Ad tracking - Trigger ad tracking information based on the presence or absence of one or more ad markers.
+ Player settings - Enable scrubbing or countdown timer functionality in the player's UI, based on the presence or absence of ad markers.

**Note**  
MediaTailor doesn't change the values for these markers. For example, if `EXT-X-CUE-OUT` has a value of `60` in the origin manifest, but no ads are placed, MediaTailor won't change the value to `0` in the personalized manifest. 

## Enable ad marker passthrough
<a name="enable-ad-marker-passthrough"></a>

You can enable ad marker passthrough using the AWS Management Console or the AWS Command Line Interface (AWS CLI).

**To enable ad marker passthrough using the console**

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

1.  Select either **New Configuration** or **Edit Configuration**.

1. In the **Advanced Settings** section, select **Enable** from the drop down menu.

**To enable ad marker passthrough using the AWS Command Line Interface (AWS CLI)**  
Use the [put-playback-configuration](https://docs.aws.amazon.com/cli/latest/reference/mediatailor/put-playback-configuration.html) command.

# HLS manifest tag handling
<a name="manifest-hls-tags"></a>

This section describes how AWS Elemental MediaTailor manages tags in the personalized output manifest.

## EXT-X-CUE tags
<a name="manifest-hls-tags-cue"></a>

MediaTailor replaces `EXT-X-CUE-OUT`, `EXT-X-CUE-OUT-CONT`, and `EXT-X-CUE-IN` tags in the input manifest with `EXT-X-DISCONTINUITY` tags in the output manifest. The `DISCONTINUITY` tags mark the following boundaries:
+ Where the main content transitions to an ad
+ Where one ad transitions to another ad
+ Where an ad transitions back to the main content

## EXT-X-DATERANGE tags
<a name="manifest-hls-tags-daterange"></a>

MediaTailor passes through `EXT-X-DATERANGE` tags from the input manifest to the output manifest. MediaTailor also inserts `EXT-X-DISCONTINUITY` tags that correspond to the `DATERANGE` tags. The `DISCONTINUITY` tags mark the following boundaries:
+ Where the main content transitions to an ad
+ Where one ad transitions to another ad
+ Where an ad transitions back to the main content

## EXT-X-KEY tags
<a name="manifest-hls-tags-key"></a>

MediaTailor passes through `EXT-X-KEY` tags from the input manifest. These tags indicate that the main content is encrypted. Since ads aren't encrypted, MediaTailor inserts `EXT-X-KEY:METHOD=NONE` at the start of an ad avail. When playback returns to the main content, MediaTailor re-enables encryption by inserting the `EXT-X-KEY` tag with the `METHOD` value defined as the encryption type.

## Unrecognized tags
<a name="manifest-hls-tags-unknown"></a>

MediaTailor passes through all unknown and custom tags from the input manifest to the output manifest.

# HLS manifest examples
<a name="manifest-hls-example"></a>

The following sections provide examples of HLS origin manifests and personalized manifests. Understanding these examples can help you configure and troubleshoot your MediaTailor workflows.

For information about how query parameters are applied to HLS manifests and segments, see [MediaTailor HLS implicit session initialization](manifest-query-parameters-hls-implicit-session-initialization.md).

## Understanding HLS playlist types
<a name="hls-playlist-overview"></a>

HTTP Live Streaming (HLS) uses two primary types of playlists:

Multivariant playlist  
A multivariant playlist is the top-level index file that lists all available renditions of the content. It contains references to media playlists but does not contain any media segments itself. This playlist allows players to select the most appropriate rendition based on network conditions, device capabilities, or user preferences.  
This playlist type is also known by several other names in various contexts, including master playlist, master manifest, primary playlist, main playlist, index file, or master M3U8.  
In MediaTailor workflows, the multivariant playlist is the entry point for playback requests and is where ad personalization begins.

Media playlist  
A media playlist contains the actual media segment information for a specific rendition (quality level) of the content. It includes timing information, segment URLs, and other metadata required for playback of a single rendition.  
This playlist type is also known as media playlist, child manifest, chunklist, media M3U8, or rendition playlist.  
In MediaTailor workflows, media playlists are personalized to include both content segments and ad segments in the proper sequence.

For more detailed information about HLS playlist types, see [HLS playlist types](hls-playlist-types.md).

## HLS origin manifest examples
<a name="manifest-hls-ex-origin"></a>

The following example shows an HLS multivariant playlist that AWS Elemental MediaTailor received by HLS from the content origin.

```
#EXTM3U
    #EXT-X-VERSION:3
    #EXT-X-INDEPENDENT-SEGMENTS
    #EXT-X-STREAM-INF:BANDWIDTH=2665726,AVERAGE-BANDWIDTH=2526299,RESOLUTION=960x540,FRAME-RATE=29.970,CODECS="avc1.640029,mp4a.40.2",SUBTITLES="subtitles"
    index_1.m3u8
    #EXT-X-STREAM-INF:BANDWIDTH=3956044,AVERAGE-BANDWIDTH=3736264,RESOLUTION=1280x720,FRAME-RATE=29.970,CODECS="avc1.640029,mp4a.40.2",SUBTITLES="subtitles"
    index_2.m3u8
    #EXT-X-STREAM-INF:BANDWIDTH=995315,AVERAGE-BANDWIDTH=951107,RESOLUTION=640x360,FRAME-RATE=29.970,CODECS="avc1.4D401E,mp4a.40.2",SUBTITLES="subtitles"
    index_3.m3u8
    #EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subtitles",NAME="caption_1",DEFAULT=YES,AUTOSELECT=YES,FORCED=NO,LANGUAGE="eng",URI="index_4_0.m3u8"
```

In this multivariant playlist example:
+ The `#EXT-X-STREAM-INF` tags define different renditions with varying resolutions and bitrates
+ Each rendition references a media playlist (such as `index_1.m3u8`)
+ The `#EXT-X-MEDIA` tag defines a subtitle track

The following example shows an HLS media playlist that AWS Elemental MediaTailor received by HLS from the content origin. This example uses `EXT-X-CUE-OUT` and `EXT-X-CUE-IN` tags to describe ad avail opportunities.

```
#EXTM3U
    #EXT-X-VERSION:3
    #EXT-X-TARGETDURATION:7
    #EXT-X-MEDIA-SEQUENCE:8779957
    #EXTINF:6.006,
    index_1_8779957.ts?m=1566416212
    #EXTINF:6.006,
    index_1_8779958.ts?m=1566416212
    #EXTINF:5.372,
    index_1_8779959.ts?m=1566416212
    #EXT-OATCLS-SCTE35:/DAlAAAAAsvhAP/wFAXwAAAGf+/+AdLfiP4AG3dAAAEBAQAAXytxmQ==
    #EXT-X-CUE-OUT:20.020
    #EXTINF:0.634,
    index_1_8779960.ts?m=1566416212
    #EXT-X-CUE-OUT-CONT:ElapsedTime=0.634,Duration=21,SCTE35=/DAlAAAAAsvhAP/wFAXwAAAGf+/+AdLfiP4AG3dAAAEBAQAAXytxmQ==
    #EXTINF:6.006,
    index_1_8779961.ts?m=1566416212
    #EXT-X-CUE-OUT-CONT:ElapsedTime=6.640,Duration=21,SCTE35=/DAlAAAAAsvhAP/wFAXwAAAGf+/+AdLfiP4AG3dAAAEBAQAAXytxmQ==
    #EXTINF:6.006,
    index_1_8779962.ts?m=1566416212
    #EXT-X-CUE-OUT-CONT:ElapsedTime=12.646,Duration=21,SCTE35=/DAlAAAAAsvhAP/wFAXwAAAGf+/+AdLfiP4AG3dAAAEBAQAAXytxmQ==
    #EXTINF:6.006,
    index_1_8779963.ts?m=1566416212
    #EXT-X-CUE-OUT-CONT:ElapsedTime=18.652,Duration=21,SCTE35=/DAlAAAAAsvhAP/wFAXwAAAGf+/+AdLfiP4AG3dAAAEBAQAAXytxmQ==
    #EXTINF:1.368,
    index_1_8779964.ts?m=1566416212
    #EXT-X-CUE-IN
    #EXTINF:4.638,
    index_1_8779965.ts?m=1566416212
    #EXTINF:6.006,
    index_1_8779966.ts?m=1566416212
    #EXTINF:6.006,
    index_1_8779967.ts?m=1566416212
    #EXTINF:6.006,
    index_1_8779968.ts?m=1566416212
```

In this media playlist example:
+ The `#EXTINF` tags specify the duration of each segment
+ The `#EXT-X-CUE-OUT` tag marks the beginning of an ad break
+ The `#EXT-X-CUE-OUT-CONT` tags provide information about the ongoing ad break
+ The `#EXT-X-CUE-IN` tag marks the end of the ad break

## HLS personalized manifest examples
<a name="manifest-hls-ex-personalized"></a>

The following example shows an HLS multivariant playlist that AWS Elemental MediaTailor personalized.

```
#EXTM3U
    #EXT-X-VERSION:3
    #EXT-X-MEDIA:LANGUAGE="eng",AUTOSELECT=YES,FORCED=NO,TYPE=SUBTITLES,URI="../../../manifest/43f3e412052f2808dd84ea1da90e92e914edddee/external-canary-hls/ee1696a8-4f7f-4c4c-99de-9821131847e8/3.m3u8",GROUP-ID="subtitles",DEFAULT=YES,NAME="caption_1"
    #EXT-X-INDEPENDENT-SEGMENTS
    #EXT-X-STREAM-INF:CODECS="avc1.640029,mp4a.40.2",AVERAGE-BANDWIDTH=2526299,RESOLUTION=960x540,SUBTITLES="subtitles",FRAME-RATE=29.97,BANDWIDTH=2665726
    ../../../manifest/43f3e412052f2808dd84ea1da90e92e914edddee/external-canary-hls/ee1696a8-4f7f-4c4c-99de-9821131847e8/0.m3u8
    #EXT-X-STREAM-INF:CODECS="avc1.640029,mp4a.40.2",AVERAGE-BANDWIDTH=3736264,RESOLUTION=1280x720,SUBTITLES="subtitles",FRAME-RATE=29.97,BANDWIDTH=3956044
    ../../../manifest/43f3e412052f2808dd84ea1da90e92e914edddee/external-canary-hls/ee1696a8-4f7f-4c4c-99de-9821131847e8/1.m3u8
    #EXT-X-STREAM-INF:CODECS="avc1.4D401E,mp4a.40.2",AVERAGE-BANDWIDTH=951107,RESOLUTION=640x360,SUBTITLES="subtitles",FRAME-RATE=29.97,BANDWIDTH=995315
    ../../../manifest/43f3e412052f2808dd84ea1da90e92e914edddee/external-canary-hls/ee1696a8-4f7f-4c4c-99de-9821131847e8/2.m3u8
```

Notice how MediaTailor has modified the media playlist URLs to include session-specific information that enables personalized ad insertion.

The following example shows a media playlist that AWS Elemental MediaTailor personalized.

```
#EXTM3U
    #EXT-X-VERSION:6
    #EXT-X-TARGETDURATION:7
    #EXT-X-MEDIA-SEQUENCE:8779957
    #EXT-X-DISCONTINUITY-SEQUENCE:0
    #EXTINF:6.006,
    https://777788889999.mediapackage.us-west-2.amazonaws.com/out/v1/e309ffd02ba8498d864dcaacff7a5ad9/index_1_8779957.ts?m=1566416212
    #EXTINF:6.006,
    https://777788889999.mediapackage.us-west-2.amazonaws.com/out/v1/e309ffd02ba8498d864dcaacff7a5ad9/index_1_8779958.ts?m=1566416212
    #EXTINF:5.372,
    https://777788889999.mediapackage.us-west-2.amazonaws.com/out/v1/e309ffd02ba8498d864dcaacff7a5ad9/index_1_8779959.ts?m=1566416212
    #EXT-X-DISCONTINUITY
    #EXTINF:3.066667,
    ../../../../segment/43f3e412052f2808dd84ea1da90e92e914edddee/external-canary-hls/ee1696a8-4f7f-4c4c-99de-9821131847e8/0/8779960
    #EXTINF:3.0,
    ../../../../segment/43f3e412052f2808dd84ea1da90e92e914edddee/external-canary-hls/ee1696a8-4f7f-4c4c-99de-9821131847e8/0/8779961
    #EXTINF:3.0,
    ../../../../segment/43f3e412052f2808dd84ea1da90e92e914edddee/external-canary-hls/ee1696a8-4f7f-4c4c-99de-9821131847e8/0/8779962
    #EXTINF:3.0,
    ../../../../segment/43f3e412052f2808dd84ea1da90e92e914edddee/external-canary-hls/ee1696a8-4f7f-4c4c-99de-9821131847e8/0/8779963
    #EXTINF:2.966667,
    ../../../../segment/43f3e412052f2808dd84ea1da90e92e914edddee/external-canary-hls/ee1696a8-4f7f-4c4c-99de-9821131847e8/0/8779964
    #EXT-X-DISCONTINUITY
    #EXTINF:6.006,
    https://777788889999.mediapackage.us-west-2.amazonaws.com/out/v1/e309ffd02ba8498d864dcaacff7a5ad9/index_1_8779963.ts?m=1566416212
    #EXTINF:1.368,
    https://777788889999.mediapackage.us-west-2.amazonaws.com/out/v1/e309ffd02ba8498d864dcaacff7a5ad9/index_1_8779964.ts?m=1566416212
    #EXTINF:4.638,
    https://777788889999.mediapackage.us-west-2.amazonaws.com/out/v1/e309ffd02ba8498d864dcaacff7a5ad9/index_1_8779965.ts?m=1566416212
    #EXTINF:6.006,
    https://777788889999.mediapackage.us-west-2.amazonaws.com/out/v1/e309ffd02ba8498d864dcaacff7a5ad9/index_1_8779966.ts?m=1566416212
    #EXTINF:6.006,
    https://777788889999.mediapackage.us-west-2.amazonaws.com/out/v1/e309ffd02ba8498d864dcaacff7a5ad9/index_1_8779967.ts?m=1566416212
    #EXTINF:6.006,
    https://777788889999.mediapackage.us-west-2.amazonaws.com/out/v1/e309ffd02ba8498d864dcaacff7a5ad9/index_1_8779968.ts?m=1566416212
```

In this personalized media playlist example:
+ MediaTailor has inserted ad segments between the content segments
+ The `#EXT-X-DISCONTINUITY` tags mark the transitions between content and ads
+ Content segments are served from the origin server (MediaPackage in this example)
+ Ad segments are served from MediaTailor's ad segment storage

## Key differences in personalized manifests
<a name="manifest-hls-key-differences"></a>

When MediaTailor personalizes HLS manifests, it makes several important changes:

Multivariant playlist changes  
+ Variant playlist URLs are rewritten to point to MediaTailor-managed URLs that include session information
+ The order of tags may be reorganized for optimal playback

Variant playlist changes  
+ Ad markers (`EXT-X-CUE-OUT`, `EXT-X-CUE-IN`) are replaced with actual ad segments
+ Discontinuity markers (`EXT-X-DISCONTINUITY`) are added at content/ad boundaries
+ Content segment URLs are rewritten to point to the origin or CDN
+ Ad segment URLs are added to point to MediaTailor's ad segment storage

Understanding these changes can help you troubleshoot issues in your MediaTailor workflows and ensure proper configuration of your CDN and player.

## Related topics
<a name="manifest-hls-related-topics"></a>

For more information about HLS manifests and MediaTailor, see the following topics:
+ [HLS playlist types](hls-playlist-types.md) - Detailed explanation of HLS playlist types
+ [Using a CDN to optimize MediaTailor ad personalization and content delivery](integrating-cdn.md) - Information about using a CDN with MediaTailor
+ [How MediaTailor ad insertion works](what-is-flow.md) - Overview of how MediaTailor ad insertion works

# Integrating an MPEG-DASH source
<a name="manifest-dash"></a>

AWS Elemental MediaTailor supports `.mpd` live and video on demand (VOD) manifests that follow the guidelines for the DASH dynamic profile. MediaTailor accepts multi-period and single-period DASH-compliant manifest inputs, and delivers multi-period DASH-compliant manifest outputs. 

Input manifests must have the following:
+ SCTE-35 event streams with splice info settings for either `splice insert `or` time signal`. The settings can be provided in clear XML or in base64-encoded binary. 
+ `Segment templates` with `segment timelines`. 

For published manifests, MediaTailor requires that updates from the origin server leave the following unchanged: 
+ Period start times, specified in the `start` attribute. 
+ Values of `presentationTimeOffset` in the segment templates of the period representations. 

As a best practice, give the ad avails the same `AdaptationSet` and `Representation` settings as the content stream periods. AWS Elemental MediaTailor uses these settings to transcode the ads to match the content stream, for smooth switching between the two.

The following sections provide more information about how MediaTailor handles ads in DASH manifests.

**Topics**
+ [DASH ad markers](dash-ad-markers.md)
+ [DASH ad avail duration](dash-ad-avail-duration.md)
+ [DASH manifest segment numbering](dash-manifest-segment-numbering.md)
+ [DASH MPD examples](manifest-dash-example.md)
+ [DASH location feature](dash-location-feature.md)

# DASH ad markers
<a name="dash-ad-markers"></a>

MediaTailor 

AWS Elemental MediaTailor uses SCTE-35 cue-out markers to identify ad avails in the DASH manifest using the following logic: 
+ **Multi-period DASH**: MediaTailor inserts ads for the first `Event` in each `Period` that contains either `SpliceInsert` or `TimeSignal` cue-out markers. MediaTailor ignores additional `Event` markers in the `Period`.
+ **Single-period DASH**: MediaTailor inserts ads each `Event` in the `Period` that contains either `SpliceInsert` or `TimeSignal` cue-out markers.

By default, AWS Elemental MediaTailor manages DASH manifests as multi-period manifests. You can change your configuration to handle single-period DASH manifests from your origin server. For information, see [Creating an MediaTailor playback configuration](configurations-create.md).

The following sections provide additional detail about DASH ad marker handling and provides decorated manifests from the origin.

## DASH origin manifest XML requirements
<a name="dash-ad-markers-examples"></a>

Ad markers in DASH manifests from the origin must be formatted properly for MediaTailor to identify ad breaks. The following topics describe these formatting requirements in clear XML.

### `SpliceInsert` in clear XML
<a name="dash-splice-xml"></a>

`SpliceInsert` ad markers in clear XML must contain the following:
+ `EventStream` must have the following attribute: `schemeIdUri=urn:scte:scte35:2013:xml`
+ `Event` must hold `scte35:SpliceInfoSection` 
+ `scte35:SpliceInfoSection` must hold `scte35:SpliceInsert` 
+ `scte35:SpliceInsert` must have the following attribute: `outOfNetworkIndicator="true"`

**Example `SpliceInsert` in XML**  
In the following example, required SCTE markers are in bold.   

```
<Period start="PT444806.040S" id="123586" duration="PT15.000S">
  <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2013:xml">
    <Event duration="1350000">
      <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="180832" tier="4095">
        <scte35:SpliceInsert spliceEventId="4026531855" spliceEventCancelIndicator="false" outOfNetworkIndicator="true" spliceImmediateFlag="false" uniqueProgramId="1" availNum="1" availsExpected="1">
            <scte35:Program><scte35:SpliceTime ptsTime="5672624400"/></scte35:Program>
            <scte35:BreakDuration autoReturn="true" duration="1350000"/>
        </scte35:SpliceInsert>
      </scte35:SpliceInfoSection>
    </Event>
  .
  .
  .
</Period>
```

### `TimeSignal` in clear XML
<a name="dash-signal-xml"></a>

`TimeSignal` ad markers in clear XML must contain the following:
+ `EventStream` must have the following attribute: `schemeIdUri=urn:scte:scte35:2013:xml`
+ `Event` must hold `scte35:SpliceInfoSection`
+ `scte35:SpliceInfoSection` must hold `scte35:TimeSignal`
+ `scte35:SpliceInfoSection` must also hold `scte35:SegmentationDescriptor`
+ `scte35:SegmentationDescriptor` must have the following attribute, where the value is a valid [Cue-out numbers](#dash-signal-xml-values): `segmentationTypeId="xx"`
+ `scte35:SegmentationDescriptor` must hold `scte35:SegmentationUpid` 
<a name="dash-signal-xml-values"></a>
**Cue-out numbers**  
The following are supported cue-out numbers for the `segmentationTypeId`.


| Segmentation message | segmentationTypeId value | Hexadecimal value | 
| --- | --- | --- | 
| Distributor advertisement end | 51 | 0x51 | 
| Distributor advertisement start | 50 | 0x32 | 
| Distributor placement opportunity end | 55 | 0x37 | 
| Distributor placement opportunity start | 54 | 0x36 | 
| End break | 35 | 0x23 | 
| Provider advertisement end | 49 | 0x31 | 
| Provider advertisement start | 48 | 0x30 | 
| Provider overlay placement opportunity end | 57 | 0x39 | 
| Provider overlay placement opportunity start | 56 | 0x38 | 
| Provider placement opportunity end | 53 | 0x35 | 
| Provider placement opportunity start | 52 | 0x34 | 
| Start break | 34 | 0x22 | 

**Example `TimeSignal` in XML**  
In the following example, required SCTE markers are in bold.   

```
<Period start="PT346530.250S" id="178443" duration="PT61.561S">
  <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2013:xml">
    <Event duration="5310000">
      <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="183003" tier="4095">
        <scte35:TimeSignal>
          <scte35:SpliceTime ptsTime="3442857000"/>
         </scte35:TimeSignal>
        <scte35:SegmentationDescriptor segmentationEventId="1414668" segmentationEventCancelIndicator="false" segmentationDuration="8100000" segmentationTypeId="52" segmentNum="0" segmentsExpected="0">
            <scte35:DeliveryRestrictions webDeliveryAllowedFlag="false" noRegionalBlackoutFlag="false" archiveAllowedFlag="false" deviceRestrictions="3"/>
            <scte35:SegmentationUpid segmentationUpidType="12" segmentationUpidLength="2">0100</scte35:SegmentationUpid>
          </scte35:SegmentationDescriptor>
        </scte35:SpliceInfoSection>
    </Event>
  .
  .
  .
</Period>
```

## DASH origin manifest base64-encoded binary requirements
<a name="dash-base64"></a>

Ad markers in DASH manifests from the origin must be formatted properly for MediaTailor to identify ad breaks. The following topics describe these formatting requirements in base64-encoded binary.

Both `TimeSignal` and `SpliceInsert` ad markers in base64-encoded manifests must contain the following:
+ `EventStream` must have the following attribute: `urn:scte:scte35:2014:xml+bin`
+ `Event` must hold `scte35:Signal`
+ `scte35:Signal` must hold `scte35:Binary` that contains a base64-encoded binary. 

The decoded binary must provide a `splice_info_section` with the same information as what's required for clear XML ad markers.
+ The command type must be either `splice_insert()` or `time_signal()`
+ The additional settings must comply with those described in [`TimeSignal` in clear XML](#dash-signal-xml) and [`SpliceInsert` in clear XML](#dash-splice-xml).

 The decoded binary must provide a `splice_info_section` with the same set of information as the clear XML would provide in a `scte35:SpliceInfoSection` element. The command type must be either `splice_insert()` or `time_signal()`, and the additional settings must comply with those described previously for clear XML delivery. 

The following example shows this option, with the required markers in bold.

```
<Period start="PT444806.040S" id="123586" duration="PT15.000S">
    <EventStream schemeIdUri="urn:scte:scte35:2014:xml+bin" timescale="1">
      <Event presentationTime="1541436240" duration="24" id="29">
        <scte35:Signal xmlns="http://www.scte.org/schemas/35/2016">
          <scte35:Binary>/DAhAAAAAAAAAP/wEAUAAAHAf+9/fgAg9YDAAAAAAAA25aoh</scte35:Binary>
        </scte35:Signal>
      </Event>
      <Event presentationTime="1541436360" duration="24" id="30">
        <scte35:Signal xmlns="http://www.scte.org/schemas/35/2016">
          <scte35:Binary>QW5vdGhlciB0ZXN0IHN0cmluZyBmb3IgZW5jb2RpbmcgdG8gQmFzZTY0IGVuY29kZWQgYmluYXJ5Lg==</scte35:Binary>
        </scte35:Signal>
      </Event>
  .
  .
  .
</Period>
```

The following is the decoded binary for the first event listed in the preceding example. The setting for `splice_command_type` is 5, which indicates `splice_insert`. 

```
{
        "table_id": 252,
        "section_syntax_indicator": false,
        "private_indicator": false,
        "section_length": 33,
        "protocol_version": 0,
        "encrypted_packet": false,
        "encryption_algorithm": 0,
        "pts_adjustment": 0,
        "cw_index": 0,
        "tier": "0xFFF",
        "splice_command_length": 16,
        "splice_command_type": 5,
        "splice_command": {
          "splice_event_id": 448,
          "splice_event_cancel_indicator": false,
          "out_of_network_indicator": true,
          "program_splice_flag": true,
          "duration_flag": true,
          "splice_immediate_flag": false,
          "utc_splice_time": {
            "time_specified_flag": false,
            "pts_time": null
          },
          "component_count": 0,
          "components": null,
          "break_duration": {
            "auto_return": false,
            "duration": {
              "pts_time": 2160000,
              "wall_clock_seconds": 24.0,
              "wall_clock_time": "00:00:24:00000"
            }
          },
          "unique_program_id": 49152,
          "avail_num": 0,
          "avails_expected": 0
        },
        "splice_descriptor_loop_length": 0,
        "splice_descriptors": null,
        "Scte35Exception": {
          "parse_status": "SCTE-35 cue parsing completed with 0 errors.",
          "error_messages": [],
          "table_id": 252,
          "splice_command_type": 5
        }
      }
```

# DASH ad avail duration
<a name="dash-ad-avail-duration"></a>

During playback, when AWS Elemental MediaTailor encounters an ad avail, it replaces some or all of the avail with ads. MediaTailor starts ad replacement at the beginning of the ad avail and includes ads as follows: 
+ If the ad avail specifies a duration, MediaTailor includes as many ads as it can fit inside the duration boundary, without overwriting content that follows. 
+ If no duration is provided, MediaTailor includes ads until it reaches the end of the ad avail. For multi-period manifests, this is the end of the period. For single-period manifests, this is the end of the event. MediaTailor doesn't play ads past the end of the ad avail and, when it encounters the end, truncates the current ad instead of overwriting the content that follows. 

**How AWS Elemental MediaTailor looks for the ad avail duration**  
AWS Elemental MediaTailor searches for a duration setting in the following order: 

1. `Event` `duration`

1. For splice insert, the `scte35:BreakDuration` `duration`

1. For time signal, the `scte35:SegmentationDescriptor` `segmentationDuration`

If AWS Elemental MediaTailor doesn't find any of these settings, it manages ad inclusion without a duration. 

The following example shows an `Event` that has a `duration`.

```
  <Period start="PT444806.040S" id="123586" duration="PT15.000S">
          <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2013:xml">
            <Event duration="1350000">
              <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="180832" tier="4095">
                <scte35:SpliceInsert spliceEventId="4026531855" spliceEventCancelIndicator="false" outOfNetworkIndicator="true" spliceImmediateFlag="false" uniqueProgramId="1" availNum="1" availsExpected="1">
                  <scte35:Program><scte35:SpliceTime ptsTime="5672624400"/></scte35:Program>
                  <scte35:BreakDuration autoReturn="true" duration="1350000"/>
                </scte35:SpliceInsert>
              </scte35:SpliceInfoSection>
            </Event>
              ...
```

The following example shows ad avail with no duration specified. The `Event` has no `duration` and the `scte35:SpliceInsert` element doesn't contain a `scte35:BreakDuration` child element.

```
  <Period start="PT444836.720S" id="123597" duration="PT12.280S">
          <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2013:xml">
            <Event>
              <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="180832" tier="4095">
                <scte35:SpliceInsert spliceEventId="4026531856" spliceEventCancelIndicator="false" outOfNetworkIndicator="true" spliceImmediateFlag="false" uniqueProgramId="1" availNum="1" availsExpected="1">
                  <scte35:Program><scte35:SpliceTime ptsTime="5675385600"/></scte35:Program>
                </scte35:SpliceInsert>
              </scte35:SpliceInfoSection>
            </Event>
            ...
```

# DASH manifest segment numbering
<a name="dash-manifest-segment-numbering"></a>

MediaTailor supports media segments in `<SegmentTemplate>` that are defined using `<SegmentTimeline>` and the `media` attribute. You can specify the media segment list in the `media` attribute using either the `$Number$` identifier or the `$Time$` identifier.

 The following example shows a `SegmentTemplate` with a `media` attribute setting that uses the `$Number$` identifier.

```
        <SegmentTemplate initialization="index_subtitles_4_0_init.mp4?m=1532451703" media="index_subtitles_4_0_$Number$.mp4?m=1532451703" presentationTimeOffset="1062336677920" startNumber="2349899" timescale="90000">
                <SegmentTimeline>
                  <S d="540540" r="2" t="1062338840080"/>
                  <S d="69069" t="1062340461700"/>
                </SegmentTimeline>
              </SegmentTemplate>
```

 The following example shows a `SegmentTemplate` with a `media` attribute setting that uses the `$Time$` identifier.

```
        <SegmentTemplate initialization="asset_720p_8000K_9_init.mp4" media="asset_720p_8000K_9_$Time$.mp4" startNumber="1" timescale="90000">
                <SegmentTimeline>
                  <S d="180000" r="2" t="0"/>
                  <S d="147000" t="540000"/>
                </SegmentTimeline>
              </SegmentTemplate>
```

# DASH MPD examples
<a name="manifest-dash-example"></a>

The following sections provide examples of DASH origin MPDs and personalized MPDs. Understanding these examples can help you configure and troubleshoot your MediaTailor workflows.

For information about how query parameters are applied to DASH manifests and segments, see [MediaTailor DASH implicit session initialization](manifest-query-parameters-dash-implicit-session-initialization.md).

## Understanding DASH MPD structure
<a name="dash-mpd-overview"></a>

Dynamic Adaptive Streaming over HTTP (DASH) uses a Media Presentation Description (MPD) manifest to deliver streaming content. The MPD is an XML document that describes the structure and availability of media content.

MPD (Media Presentation Description)  
The MPD is the primary manifest file in DASH streaming that describes the structure and availability of media content. It contains information about periods, adaptation sets, representations, and segments that make up the streaming content.  
This manifest type is also known by several other names in various contexts, including DASH manifest, DASH MPD, master manifest (when comparing to HLS), or presentation manifest.  
In MediaTailor workflows, the MPD is the entry point for playback requests and is where ad personalization begins.

Period  
A Period is a temporal section of a DASH presentation. Each Period contains one or more adaptation sets and represents a span of media time. In ad insertion workflows, separate Periods are typically used to delineate between content and ads.  
In MediaTailor workflows, Periods are used to separate main content from ad content, with each ad typically represented by its own Period.

AdaptationSet  
An AdaptationSet groups a set of interchangeable encoded versions of one or several media content components. For example, one AdaptationSet might contain multiple video quality levels, while another might contain multiple audio language options.  
In MediaTailor workflows, AdaptationSets are preserved during ad insertion to maintain consistent media types between content and ads.

Representation  
A Representation is a specific encoded version of the media content within an AdaptationSet. Each Representation typically differs in bitrate, resolution, or other encoding parameters, allowing clients to select the most appropriate version based on network conditions and device capabilities.  
In MediaTailor workflows, Representations in ad Periods are matched as closely as possible to the Representations in content Periods to ensure a smooth viewing experience.

For more detailed information about DASH manifest types, see [DASH manifest types](dash-manifest-types.md).

For information about DASH manifest structure and configuration in AWS Elemental MediaPackage, see the MediaPackage User Guide section on DASH overview.

## Live DASH MPD examples
<a name="dash-manifest-live-examples"></a>

This section provides examples of live DASH MPDs. Each example lists an MPD as received from the origin server and after MediaTailor has personalized the MPD with ads.

### DASH MPD splice insert example
<a name="dash-manifest-splice-insert-example"></a>

**DASH origin MPD example for splice insert**  
The following example from an MPD shows an ad avail in a manifest received by DASH from the content origin. This example uses the `SpliceInsert` marker to indicate an ad avail.

```
<Period start="PT173402.036S" id="46041">
  <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2013:xml">
    <Event duration="9450000">
      <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="183265" tier="4095">
        <scte35:SpliceInsert spliceEventId="99" spliceEventCancelIndicator="false" outOfNetworkIndicator="true" spliceImmediateFlag="false" uniqueProgramId="1" availNum="1" availsExpected="1">
          <scte35:Program><scte35:SpliceTime ptsTime="7835775000"/></scte35:Program>
          <scte35:BreakDuration autoReturn="true" duration="9450000"/>
        </scte35:SpliceInsert>
        <scte35:SegmentationDescriptor segmentationEventId="99" segmentationEventCancelIndicator="false" segmentationDuration="9450000">
          <scte35:DeliveryRestrictions webDeliveryAllowedFlag="true" noRegionalBlackoutFlag="true" archiveAllowedFlag="true" deviceRestrictions="3"/>
          <scte35:SegmentationUpid segmentationUpidType="8" segmentationUpidLength="0"/>
          <scte35:SegmentationTypeID segmentationType="52"/>
          <scte35:SegmentNum segmentNum="1"/>
          <scte35:SegmentsExpected segmentsExpected="1"/>
        </scte35:SegmentationDescriptor>
      </scte35:SpliceInfoSection>
    </Event>
  </EventStream>
  <AdaptationSet mimeType="video/mp4" segmentAlignment="true" subsegmentAlignment="true" startWithSAP="1" subsegmentStartsWithSAP="1" bitstreamSwitching="true">
    <Representation id="1" width="960" height="540" frameRate="30000/1001" bandwidth="1000000" codecs="avc1.4D401F">
      <SegmentTemplate timescale="30000" media="index_video_1_0_$Number$.mp4?m=1528475245" initialization="index_video_1_0_init.mp4?m=1528475245" startNumber="178444" presentationTimeOffset="10395907501">
        <SegmentTimeline>
          <S t="10395907501" d="60060" r="29"/>
          <S t="10397709301" d="45045"/>
        </SegmentTimeline>
      </SegmentTemplate>
    </Representation>
  </AdaptationSet>
  <AdaptationSet mimeType="audio/mp4" segmentAlignment="0" lang="eng">
    <Representation id="2" bandwidth="96964" audioSamplingRate="48000" codecs="mp4a.40.2">
      <SegmentTemplate timescale="48000" media="index_audio_2_0_$Number$.mp4?m=1528475245" initialization="index_audio_2_0_init.mp4?m=1528475245" startNumber="178444" presentationTimeOffset="16633452001">
        <SegmentTimeline>
          <S t="16633452289" d="96256" r="3"/>
          <S t="16633837313" d="95232"/>
          <S t="16633932545" d="96256" r="4"/>
          <S t="16634413825" d="95232"/>
          <S t="16634509057" d="96256" r="5"/>
          <S t="16635086593" d="95232"/>
          <S t="16635181825" d="96256" r="4"/>
          <S t="16635663105" d="95232"/>
          <S t="16635758337" d="96256" r="5"/>
          <S t="16636335873" d="71680"/>
        </SegmentTimeline>
      </SegmentTemplate>
    </Representation>
  </AdaptationSet>
</Period>
```

In this origin MPD example:
+ The `<EventStream>` element contains SCTE-35 markers that indicate ad avails
+ The `<scte35:SpliceInsert>` element provides details about the ad avail
+ The `<scte35:BreakDuration>` element specifies the duration of the ad break
+ The `<AdaptationSet>` elements define the available video and audio streams

**DASH personalized MPD example for splice insert**  
AWS Elemental MediaTailor personalizes the ad avails with advertising specifications. The personalizations reflect the viewer data that is received from the player and the advertising campaigns that are currently underway. 

The following example shows an ad avail after AWS Elemental MediaTailor personalizes it. 

```
<Period id="178443_1" start="PT96H15M30.25S">
  <BaseURL>http://111122223333.cloudfront.net/nbc_fallback_2/</BaseURL>
  <AdaptationSet bitstreamSwitching="false" frameRate="30/1" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1">
    <SegmentTemplate startNumber="1" timescale="90000"/>
    <Representation bandwidth="10000000" codecs="avc1.640028" height="1080" id="1" width="1920">
      <SegmentTemplate initialization="nbc_fallback_ad_2_1080p_10init.mp4" media="nbc_fallback_ad_2_1080p_10_$Number%09d$.mp4" startNumber="1" timescale="90000">
        <SegmentTimeline>
          <S d="180000" r="13" t="0"/>
          <S d="176940" t="2520000"/>
        </SegmentTimeline>
      </SegmentTemplate>
    </Representation>
    <Representation bandwidth="4000000" codecs="avc1.64001f" height="720" id="2" width="1280">
      <SegmentTemplate initialization="nbc_fallback_ad_2_720p_9init.mp4" media="nbc_fallback_ad_2_720p_9_$Number%09d$.mp4" startNumber="1" timescale="90000">
        <SegmentTimeline>
          <S d="180000" r="13" t="0"/>
          <S d="176940" t="2520000"/>
        </SegmentTimeline>
      </SegmentTemplate>
    </Representation>
  </AdaptationSet>
  <AdaptationSet mimeType="audio/mp4" segmentAlignment="0" lang="eng">
    <Representation id="8" bandwidth="128000" audioSamplingRate="48000" codecs="mp4a.40.2">
      <SegmentTemplate initialization="nbc_fallback_ad_2_audio_2init.mp4" media="nbc_fallback_ad_2_audio_2_$Number%09d$.mp4" startNumber="1" timescale="90000">
        <SegmentTimeline>
          <S d="180000" r="13" t="0"/>
          <S d="176940" t="2520000"/>
        </SegmentTimeline>
      </SegmentTemplate>
    </Representation>
  </AdaptationSet>
</Period>
```

In this personalized MPD example:
+ MediaTailor has created a new Period for the ad content
+ The `<BaseURL>` element points to the ad content location
+ The `<AdaptationSet>` elements maintain similar structure to the content
+ The `<Representation>` elements provide different quality levels for the ad content

### DASH MPD time signal example
<a name="dash-manifest-time-signal-example"></a>

**DASH origin MPD example for time signal**  
The following example from an MPD shows an ad avail in a manifest received by DASH from the content origin. This example uses the `TimeSignal` marker to indicate an ad avail.

```
<Period start="PT173402.036S" id="46041">
  <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2013:xml">
    <Event duration="9450000">
      <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="183265" tier="4095">
        <scte35:TimeSignal>
          <scte35:SpliceTime ptsTime="7835775000"/>
        </scte35:TimeSignal>
        <scte35:SegmentationDescriptor segmentationEventId="99" segmentationEventCancelIndicator="false" segmentationDuration="9450000">
          <scte35:DeliveryRestrictions webDeliveryAllowedFlag="true" noRegionalBlackoutFlag="true" archiveAllowedFlag="true" deviceRestrictions="3"/>
          <scte35:SegmentationUpid segmentationUpidType="8" segmentationUpidLength="0"/>
          <scte35:SegmentationTypeID segmentationType="52"/>
          <scte35:SegmentNum segmentNum="1"/>
          <scte35:SegmentsExpected segmentsExpected="1"/>
        </scte35:SegmentationDescriptor>
      </scte35:SpliceInfoSection>
    </Event>
  </EventStream>
  <AdaptationSet mimeType="video/mp4" segmentAlignment="true" subsegmentAlignment="true" startWithSAP="1" subsegmentStartsWithSAP="1" bitstreamSwitching="true">
    <Representation id="1" width="960" height="540" frameRate="30000/1001" bandwidth="1000000" codecs="avc1.4D401F">
      <SegmentTemplate timescale="30000" media="index_video_1_0_$Number$.mp4?m=1528475245" initialization="index_video_1_0_init.mp4?m=1528475245" startNumber="178444" presentationTimeOffset="10395907501">
        <SegmentTimeline>
          <S t="10395907501" d="60060" r="29"/>
          <S t="10397709301" d="45045"/>
        </SegmentTimeline>
      </SegmentTemplate>
    </Representation>
  </AdaptationSet>
</Period>
```

In this origin MPD example:
+ The `<scte35:TimeSignal>` element is used instead of `<scte35:SpliceInsert>`
+ The `<scte35:SegmentationDescriptor>` provides additional information about the ad avail

**DASH personalized MPD example for time signal**  
AWS Elemental MediaTailor personalizes the ad avails with advertising specifications. The personalizations reflect the viewer data that is received from the player and the advertising campaigns that are currently underway. 

The following example shows an ad avail after AWS Elemental MediaTailor personalizes it. 

```
<Period id="178443_1" start="PT96H15M30.25S">
  <BaseURL>http://111122223333.cloudfront.net/nbc_fallback_2/</BaseURL>
  <AdaptationSet bitstreamSwitching="false" frameRate="30/1" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1">
    <SegmentTemplate startNumber="1" timescale="90000"/>
    <Representation bandwidth="10000000" codecs="avc1.640028" height="1080" id="1" width="1920">
      <SegmentTemplate initialization="nbc_fallback_ad_2_1080p_10init.mp4" media="nbc_fallback_ad_2_1080p_10_$Number%09d$.mp4" startNumber="1" timescale="90000">
        <SegmentTimeline>
          <S d="180000" r="13" t="0"/>
          <S d="176940" t="2520000"/>
        </SegmentTimeline>
      </SegmentTemplate>
    </Representation>
  </AdaptationSet>
</Period>
```

The personalized MPD for time signal is similar to the one for splice insert, with MediaTailor creating a new Period for the ad content.

## VOD DASH MPD examples
<a name="dash-manifest-vod-examples"></a>

This section provides examples of video on demand (VOD) DASH MPDs. Each example lists an MPD as received from the origin server and after MediaTailor has personalized the MPD with ads.

VOD DASH MPDs follow the same structure as live MPDs, but they typically have a `type="static"` attribute in the MPD element and may contain multiple Periods for different content segments.

For examples of VOD DASH MPDs, see the MediaTailor documentation on [DASH ad markers](dash-ad-markers.md).

## Key differences in personalized MPDs
<a name="dash-manifest-key-differences"></a>

When MediaTailor personalizes DASH MPDs, it makes several important changes:

Period handling  
+ New Periods are created for ad content
+ Period start times are adjusted to maintain timeline continuity
+ EventStream elements with SCTE-35 markers are processed and removed

AdaptationSet and Representation handling  
+ AdaptationSets in ad Periods are created to match content AdaptationSets
+ Representations are created for different quality levels of the ad content
+ SegmentTemplate elements are updated to point to ad content

Understanding these changes can help you troubleshoot issues in your MediaTailor workflows and ensure proper configuration of your CDN and player.

## Related topics
<a name="dash-manifest-related-topics"></a>

For more information about DASH MPDs and MediaTailor, see the following topics:
+ [DASH manifest types](dash-manifest-types.md) - Detailed explanation of DASH manifest types
+ [Using a CDN to optimize MediaTailor ad personalization and content delivery](integrating-cdn.md) - Information about using a CDN with MediaTailor
+ [How MediaTailor ad insertion works](what-is-flow.md) - Overview of how MediaTailor ad insertion works
+ For comprehensive information about DASH manifest structure and MediaPackage configuration, see the MediaPackage User Guide section on DASH overview.

# DASH location feature
<a name="dash-location-feature"></a>

This section provides information about the location feature for DASH, which is enabled by default in AWS Elemental MediaTailor. Read this section if you create content delivery network (CDN) routing rules for accessing MediaTailor manifests. Also read this section if you use server-side reporting with players that don't support sticky HTTP redirects.

**What is the location feature?**  
The location feature allows players that don't support sticky HTTP redirects to provide sticky behavior in their manifest update requests. 

AWS Elemental MediaTailor uses sessionless initialization, and it requires sticky HTTP redirect behavior from its players. With server-side reporting, when the player makes a request for a manifest update to MediaTailor, the service issues a 302 temporary redirect, to direct the player to an endpoint for the personalized manifest. MediaTailor includes a session ID in the response, as a query parameter. The intent is for the player to follow the URL for the entirety of the session, but players that don't support sticky HTTP redirects drop the redirect and return to the original URL. When a player returns to the original URL, for each new request MediaTailor creates a new session rather than staying with the original session. This can cause the manifest to become corrupt. 

The DASH specification provides a solution to this problem in the location feature, which is enabled by default in AWS Elemental MediaTailor configurations. When this feature is enabled, MediaTailor puts the absolute URL in the manifest `<Location>` tag. Players that don't support sticky HTTP redirects can use the URL provided in `<Location>` to request updates to the manifest. 

**Do I need to disable the location feature in my configuration?**  
The location feature overrides any CDN routing rules that you set up for accessing AWS Elemental MediaTailor manifests, so you might need to disable it. The location feature doesn't affect CDN caching of content or ad segments. 

Find your situation in the following list to determine whether you need to disable the location feature for your configuration and how to handle it:
+ If you don't have CDN routing rules set up for accessing AWS Elemental MediaTailor manifests, leave the location setting enabled. 
+ Otherwise, use the following rules:
  + If you either don't use server-side reporting or your players all support sticky HTTP redirects, disable the location feature. For information about how to do this on the console, see [Creating an MediaTailor playback configuration](configurations-create.md).
  + Otherwise, contact [AWS Support](https://aws.amazon.com/premiumsupport/).

**Do I need to use the location feature?**  
You need to use the location feature for players that don't support sticky HTTP redirects. Use the URL provided in the `<Location>` tag for all of your manifest update requests. 

**Example**  
Example URLs and example `<Location>` tag.
+   
**Example: Initial request URL**  

  ```
  https://777788889999.mediatailor.us-east-1.amazonaws.com/v1/dash/5ca4c1892b1f213a1247fad47b3e34c454a7d490/testLocationTag/index.mpd
  ```
+   
**Example: Redirected 302 response**  

  ```
  /v1/dash/5ca4c1892b1f213a1247fad47b3e34c454a7d490/testLocationTag/index.mpd?aws.sessionId=0e5d9b45-ae97-49eb-901b-893d043e0aa6
  ```
+   
**Example: Location tag in a manifest**  

  ```
  <Location>https://777788889999.mediatailor.us-east-1.amazonaws.com/v1/dash/5ca4c1892b1f213a1247fad47b3e34c454a7d490/testLocationTag/index.mpd?aws.sessionId=0e5d9b45-ae97-49eb-901b-893d043e0aa6</Location>
  ```

# Securing AWS Elemental MediaTailor origin interactions with SigV4
<a name="origin-sigv4"></a>

Signature Version 4 (SigV4) is a signing protocol used to authenticate MediaTailor requests to supported origins over HTTPS. MediaTailor only supports HTTPS communication and does not allow HTTP connections. With SigV4 signing, MediaTailor includes a signed authorization header in the HTTPS origin request to MediaTailor Channel Assembly, Amazon S3 and AWS Elemental MediaPackage version 2. 

You can use SigV4 at your origin to ensure that manifest requests are only fulfilled if they’re from MediaTailor and contain a signed authorization header. This way, unauthorized MediaTailor playback configurations are blocked from accessing your origin content. If the signed authorization header is valid, your origin fulfills the request. If it isn't valid, the request fails.

The following sections describe requirements for using MediaTailor SigV4 signing to supported origins.

## MediaTailor Channel Assembly requirements
<a name="origin-sigv4-ca"></a>

If you use SigV4 to protect your MediaTailor Channel Assembly origin, the following requirements must be met for MediaTailor to access the manifest:
+ The origin base URL in your MediaTailor configuration must be a Channel Assembly channel in the following format: `channel-assembly.mediatailor.region.amazonaws.com`
+ Your origin must be configured to use HTTPS. MediaTailor only supports HTTPS communication and does not allow HTTP connections. If HTTPS is not enabled at the origin, MediaTailor will not sign the request.
+ Your channel must have an origin access policy that includes the following:
  + Principal access for MediaTailor to access your channel. Grant access to **mediatailor.amazonaws.com**.
  + IAM permissions **mediatailor:GetManifest **to read all multivariant playlists referenced by the MediaTailor configuration.

  For information about setting a policy on the channel, see [Create a channel using the MediaTailor console](channel-assembly-creating-channels.md).

**Example origin access policy for Channel Assembly, scoped to the MediaTailor configuration account**  

```
{
    "Effect": "Allow",
    "Principal": {"Service": "mediatailor.amazonaws.com"},
    "Action": "mediatailor:GetManifest",
    "Resource": "arn:aws:mediatailor:us-west-2:777788889999:channel/ca-origin-channel",
    "Condition": {
        "StringEquals": {"AWS:SourceAccount": "777788889999"}
    }
}
```

**Example origin access policy for Channel Assembly, scoped to the MediaTailor playback configuration**  

```
{
    "Effect": "Allow",
    "Principal": {"Service": "mediatailor.amazonaws.com"},
    "Action": "mediatailor:GetManifest",
    "Resource": "arn:aws:mediatailor:us-west-2:777788889999:channel/ca-origin-channel",
    "Condition": {
        "StringEquals": {"AWS:SourceArn": "arn:aws:mediatailor:us-west-2:777788889999:playbackConfiguration/test"}
    }
}
```

## Amazon S3 requirements
<a name="origin-sigv4-s3"></a>

If you use SigV4 to protect your Amazon S3 origin, the following requirements must be met for MediaTailor to access the manifest:
+ The origin base URL in your MediaTailor configuration must be an S3 bucket in the following format: `s3.region.amazonaws.com`
+ Your origin must be configured to use HTTPS. MediaTailor only supports HTTPS communication and does not allow HTTP connections. If HTTPS is not enabled at the origin, MediaTailor will not sign the request.
+ Your channel must have an origin access policy that includes the following:
  + Principal access for MediaTailor to access your bucket. Grant access to **mediatailor.amazonaws.com.** 

    For information about configuring access in IAM, see [Access management](https://docs.aws.amazon.com/) in the *AWS Identity and Access Management User Guide*. 
  + IAM permissions **s3:GetObject **to read all top-level manifests referenced by the MediaTailor configuration.

 For general information about SigV4 for Amazon S3, see the [Authenticating Requests (AWS Signature Version 4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) topic in the *Amazon S3 API reference*. 

**Example origin access policy for Amazon S3, scoped to the MediaTailor account**  

```
{
    "Effect": "Allow",
    "Principal": {"Service": "mediatailor.amazonaws.com"},
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::mybucket/*",
    "Condition": {
        "StringEquals": {"AWS:SourceAccount": "111122223333"}
    }
}
```

**Example origin access policy for Amazon S3, scoped to the MediaTailor playback configuration**  

```
{
    "Effect": "Allow",
    "Principal": {"Service": "mediatailor.amazonaws.com"},
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::mybucket/*",
    "Condition": {
        "StringEquals": {"AWS:SourceArn": "arn:aws:mediatailor:us-west-2:111122223333:playbackConfiguration/test”}
    }
}
```

## MediaPackage requirements
<a name="origin-sigv4-mp"></a>

If you use SigV4 to protect your MediaPackage v2 origin, the following requirements must be met for MediaTailor to access the manifest:
+ The origin base URL in your MediaTailor configuration must be a MediaPackage v2 endpoint in the following format: `mediapackagev2.region.amazonaws.com`
+ Your origin must be configured to use HTTPS. MediaTailor only supports HTTPS communication and does not allow HTTP connections. If HTTPS is not enabled at the origin, MediaTailor will not sign the request.
+ Your channel must have an origin access policy that includes the following:
  + Principal access for MediaTailor to access your endpoint. Grant access to **mediatailor.amazonaws.com.** 
  + IAM permissions **mediapackagev2:GetObject **to read all multivariant playlists referenced by the MediaTailor configuration.

 For general information about SigV4 for MediaPackage v2, see the [Authenticating Requests (AWS Signature Version 4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) topic in the *MediaPackage v2 API reference*.

**Example origin access policy for MediaPackage v2, scoped to the MediaTailor account**  

```
{
    "Effect": "Allow",
    "Principal": {"Service": "mediatailor.amazonaws.com"},
    "Action": "mediapackagev2:GetObject",
    "Resource": "arn:aws:mediapackagev2:us-west-2:444455556666:channelGroup/emp-origin-channel-group/channel/emp-origin-channel/originEndpoint/emp-origin-endpoint",
    "Condition": {
        "StringEquals": {"AWS:SourceAccount": "444455556666"}
    }
}
```

**Example origin access policy for MediaPackage v2, scoped to the MediaTailor playback configuration**  

```
{
    "Effect": "Allow",
    "Principal": {"Service": "mediatailor.amazonaws.com"},
    "Action": "mediapackagev2:GetObject",
    "Resource": "arn:aws:mediapackagev2:us-west-2:444455556666:channelGroup/emp-origin-channel-group/channel/emp-origin-channel/originEndpoint/emp-origin-endpoint",
    "Condition": {
        "StringEquals": {"AWS:SourceArn": "arn:aws:mediatailor:us-west-2:444455556666:playbackConfiguration/test”"}
    }
}
```

# Integrating AWS Elemental MediaTailor with Google Ad Manager
<a name="gam-integration"></a>

Integrate MediaTailor with [Google Ad Manager](https://admanager.google.com/home/) (Ad Manager) for programmatic access to an online, auction-driven marketplace where ad impressions can be bought and sold in real time. You must have an account set up with Ad Manager, then you can integrate with Ad Manager in the following ways:
+ A server-side integration using an SSL certificate. 
+ A client-side player integration using the Programmatic Access Libraries (PAL) SDK. This integration is required if you want to use the open auction transaction type.

Ad Manager support for programmatic transaction types varies based on the type of integration that you're using. For a list of available options, see [Transaction types](https://support.google.com/admanager/answer/2805834?hl=en) or contact your Google account team. 

The following sections describe these integrations in detail.

**Topics**
+ [Server-side integration](gam-integration-ssl.md)
+ [Client-side integration](gam-integration-pal.md)

# Server-side AWS Elemental MediaTailor integration with Google Ad Manager
<a name="gam-integration-ssl"></a>

Server-side ad requests to Google Ad Manager (Ad Manager) must include the SSL certificate that Ad Manager has issued to MediaTailor to authorize programmatic transactions. 

**To make server-side ad requests to Ad Manager**

1. [Submit an AWS Support ticket](https://console.aws.amazon.com/support/home#/) to request SSL certificates to be enabled. Include the following information in the Support ticket:
   + AWS Region
   + AWS account ID
   + MediaTailor playback configuration name

   If you don't enable SSL certificates, Ad Manager responds to MediaTailor ad requests with HTTP 401 error codes in the `ERROR_ADS_INVALID_RESPONSE` ADS interaction log event type.

1. After SSL certificates are enabled, update the URL and parameters for your ADS and preroll ADS in the playback configuration. To update or create a playback configuration, see [MediaTailor playback configuration management](working-with-configurations.md).

   For official guidance on VAST ad request URL parameters for Ad Manager, see the Ad Manager [Server-side implementation guide.](https://support.google.com/admanager/answer/10668760) Updating includes the following changes:
   + Change the base URL from `pubads.g.doubleclick.net` to `serverside.doubleclick.net`.
   + Add the parameter `ssss=mediatailor`. This indicates that MediaTailor is the server-side stitching source.
   + Remove the `IP` parameter. MediaTailor automatically passes in the end-user IP address using the `X-Forwarded-For` header.
   + Remove the `ss_req=1` parameter.

   For updated and complete VAST URL guidance, see the [Server-side implementation guide](https://support.google.com/admanager/answer/10668760) or contact your Google account team. 

# Client-side AWS Elemental MediaTailor integration with Google Ad Manager
<a name="gam-integration-pal"></a>

A MediaTailor client-side integration is required to use the Google Ad Manager Programmatic Access Libraries (PAL) SDKs. This integration is required if you want to use Ad Manager's open auction transaction type. 

The PAL SDKs provide information about the content, device, and user data for a playback session. Through the PAL SDK, you can provide this information to Google Ad Manager, which can then make better determinations of what targeted ads to show. SDKs are available for Android, iOS, HTML5, and Cast. For information about using the PAL SDKs, see [Google Ad Manager PAL SDK](https://developers.google.com/ad-manager/pal). 

**To create client-side integration with Ad Manager**

1. Use the PAL SDK to generate a nonce. 

   The nonce is an encrypted string that PAL generates for stream requests. Each request must have a unique nonce. For information about setting up a nonce, choose your SDK from [Google Ad Manager PAL SDK](https://developers.google.com/ad-manager/pal).

1. Use the `givn` parameter in your ADS request to pass through the nonce value. To do this, update your ADS URL to include `&givn=[player_params.givn]`. For instructions, see [Enabling client-side tracking](ad-reporting-client-side.md#ad-reporting-client-side-enabling).

**Datazoom player SDKs**  
MediaTailor has partnered with Datazoom to provide free player SDKs to ease integrations with SDKs such as those offered in the Ad Manager PAL. For information about the Datazoom and MediaTailor partnership, see [Datazoom free player SDKs](ad-reporting-client-side-ad-tracking-integrations.md#ad-reporting-client-side-ad-tracking-integrations-dz).

To access the Datazoom player SDKs, use the contact information on the [Datazoom with AWS](https://www.datazoom.io/partner-aws) site. 

# Customizing ad break behavior with ad break suppression
<a name="ad-rules"></a>

When you create a configuration in AWS Elemental MediaTailor, you can specify optional ad break configuration settings that govern the behavior of ad breaks, including the ability to configure ad break suppression. This allows you to tailor the ad break experiences for your video content to meet your specific requirements.

**Compatibility restrictions**  
You can't use ad break suppression with the following:
+  VOD and live-to-VOD workflows. Only live workflows are supported.
+ Server-guided ad insertion (SGAI) methods. Server-guided methods handle ad decisioning differently and don't require suppression configuration.

**Topics**
+ [Configuring ad break suppression](#ad-suppression)

## Configuring ad break suppression
<a name="ad-suppression"></a>

You can configure MediaTailor to skip ad break personalization for live content. This is known as *ad break suppression*, or *avail suppression*. This topic shows you how, and it also explains how configuring ad break suppression works.

Ad break suppression can be used for the following use cases:
+ **Large manifest lookback window** – If a viewer starts playback at the live edge of a manifest but the lookback window is large, you might want to only insert ads starting after the viewer started watching. Or, insert ads for a portion of the total lookback window in the manifest. You can configure ad suppression so that MediaTailor personalizes ad breaks on or within a specified time range behind the live edge.
+ **Mid-break join** – If the viewer starts watching a live video stream in the middle of an ad break, that user is likely to change the channel and not watch the advertisement. With ad suppression, you can skip ad break personalization if the ad break started before the viewer joined the stream.

### Configuring ad suppression
<a name="working-with-ad-suppression"></a>

To use ad suppression, you configure an **avail suppression mode**, **avail suppression value**, and **avail suppression fill policy** in the following ways: 
+ In the MediaTailor console
+ Using the AWS Command Line Interface (AWS CLI)
+ Using MediaTailor API, or as parameters in your client's playback session request

For information about configuration with parameters, see [Configuring ad suppression parameters – playback session request](#configuring-ad-suppression-parameters-playback-session-request).

#### Ad suppression configuration parameters
<a name="ad-suppression-configuration-parameters"></a>

You can choose to turn on or turn off ad suppression. If you turn on ad suppression, you specify whether that suppression happens after the live playback edge or before the live playback edge of a live stream. In either case, you also specify a time, relative to the live edge, where MediaTailor doesn't personalize ads. When you turn on avail suppression, you can specify an avail suppression policy that MediaTailor uses for partial ad-break fills when a session starts mid-break.

The following are the ad suppression configuration parameters:
+ **Avail suppression mode** – Sets the ad suppression mode. By default, ad suppression is off. **Accepted values**: `OFF`, `BEHIND_LIVE_EDGE`, or `AFTER_LIVE_EDGE`.
  + `OFF`: There is no ad suppression and MediaTailor personalizes all ad breaks.
  + `BEHIND_LIVE_EDGE`: MediaTailor doesn't personalize ad breaks that start before the live edge, minus the **Avail suppression value**. This affects the entire ad break, not just individual ad avails.
  + `AFTER_LIVE_EDGE`: MediaTailor doesn't personalize ad breaks that are within the live edge, plus the **Avail suppression value**. This can be configured to affect either entire ad breaks or allow partial filling of ad avails.
+ **Avail suppression value** – A time relative to the live edge in a live stream. **Accepted value**: A time value in `HH:MM:SS`.
+ **Avail suppression fill policy** – Defines the policy that MediaTailor applies to the **Avail suppression mode**. **Accepted values**: `PARTIAL_AVAIL`, `FULL_AVAIL_ONLY`.
  + `BEHIND_LIVE_EDGE` mode always uses the `FULL_AVAIL_ONLY` suppression policy. 
  + `AFTER_LIVE_EDGE` mode can be used to invoke `PARTIAL_AVAIL` ad break fills when a session starts mid-break.

#### Ad suppression settings examples
<a name="ad-suppression-settings-examples"></a>

The way in which the [ad suppression configuration parameters](#ad-suppression-configuration-parameters) interact with one another lets you specify several different ways to handle ad suppression and avail filling before, at, or after the live edge of the live stream. This section provides examples that show you some of these interactions. Use these examples to help you set up the configuration parameters for your particular situation.

The following are examples of ad suppression settings:

**Example 1: No ad suppression**  
When the **avail suppression mode** is `OFF`, there is no ad suppression and MediaTailor personalizes all ad breaks.  
In the following figure, various blocks are arranged horizontally along a timeline that progresses from left to right. Each block represents a portion of time where the content of the live stream or a personalized ad break plays. A dotted line represents the current live edge of the live stream. Two ad breaks occur before the live edge, and another ad break is in progress at the live edge. As shown in the figure, when the avail suppression mode is `OFF`, MediaTailor personalizes all ad breaks that occur before the live edge on the timeline. MediaTailor also personalizes the ad break in progress at the live edge.  

![\[MediaTailor ad break personalization with avail suppression mode set to OFF.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/no_ad_suppression.png)


**Example 2: `BEHIND_LIVE_EDGE` ad suppression with value in sync with live edge**  
When **avail suppression mode** is set to `BEHIND_LIVE_EDGE` and the **avail suppression value** is set to `00:00:00`, the avail suppression value is in sync with the live edge. MediaTailor doesn't personalize any ad breaks that start on or before the live edge.  
In the following figure, various blocks are arranged horizontally along a timeline that progresses from left to right. Each block represents a portion of time where the content of the live stream, a personalized ad break, or a non-personalized ad break plays. A dotted line represents the current live edge of the live stream. Another dotted line, representing the avail suppression value set to `00:00:00`, overlaps the dotted line for the live edge. Two ad breaks occur before the live edge, and another ad break occurs after the live edge. As shown in the figure, when the avail suppression mode is set to `BEHIND_LIVE_EDGE`, and the avail suppression value is set to `00:00:00` so that it's in sync with the live edge, MediaTailor doesn't personalize any ad breaks that occur before the live edge on the timeline. MediaTailor personalizes the ad break that occurs *after* the live edge.  

![\[MediaTailor ad break personalization with avail suppression mode set to BEHIND_LIVE_EDGE and avail suppression value set to 00:00:00.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/ad_supp_value_sync_live_edge.png)


**Example 3: `BEHIND_LIVE_EDGE` ad suppression with value behind live edge**  
When the **avail suppression mode** is set to `BEHIND_LIVE_EDGE`, MediaTailor doesn't personalize any ad breaks on or before that time. In this example, MediaTailor personalizes ad breaks that start up to 45 minutes behind the live edge. MediaTailor *doesn't* personalize ad breaks that start more than 45 minutes behind the live edge.  
In the following figure, various blocks are arranged horizontally along a timeline that progresses from left to right. Each block represents a portion of time where the content of the live stream, a personalized ad break, or a non-personalized ad break plays. A dotted line represents the current live edge of the live stream. Another dotted line, representing the avail suppression value set to `00:45:00`, occurs 45 minutes earlier in the timeline with respect to the dotted line for the live edge. The 45-minute time period between the dotted lines represents the avail suppression period. An ad break is in progress at the beginning of the avail suppression period. Two other ad breaks occur during the avail suppression period. As shown in the figure, when the avail suppression mode is set to `BEHIND_LIVE_EDGE`, and the avail suppression value is set to `00:45:00` behind the live edge, MediaTailor personalizes any ad breaks that occur within the avail suppression period. MediaTailor *doesn't* personalize the ad break in progress at the beginning of the avail suppression period.  

![\[MediaTailor ad break personalization with avail suppression mode set to BEHIND_LIVE_EDGE and avail suppression value set to 00:45:00.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/ad_supp_value_offset_live_edge.png)


**Example 4: `AFTER_LIVE_EDGE` ad suppression with no ad breaks occurring during the avail suppression period**  
When the **avail suppression mode** is set to `AFTER_LIVE_EDGE` and the **avail suppression value** is greater than zero, MediaTailor doesn't personalize any ad breaks until the elapsed time of the session has reached that value.  
In the following figure, various blocks are arranged horizontally along a timeline that progresses from left to right. Each block represents a portion of time where the content of the live stream or a personalized ad break plays. A dotted line represents the current live edge of the live stream. Another dotted line, representing the avail suppression value set to `00:30:00`, occurs 30 minutes later in the timeline with respect to the dotted line for the live edge. A third dotted line, representing the session initialization, occurs earlier in the timeline with respect to the dotted line for the live edge. The 30-minute time period between the live-edge time and the avail-suppression-value time represents the avail suppression period. An ad break occurs after the avail suppression period. As shown in the figure, when the avail suppression mode is set to `AFTER_LIVE_EDGE`, the avail suppression value is set to `00:30:00` after the live edge, and the session initialization occurs before the live edge, MediaTailor personalizes any ad breaks that occur *after* the avail suppression period.  

![\[MediaTailor ad break personalization with avail suppression mode set to AFTER_LIVE_EDGE, avail suppression value set to 00:30:00, and session initialization occurring before the live edge.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/ad_supp_after_no_ad_break.png)


**Example 5: `AFTER_LIVE_EDGE` ad suppression with `PARTIAL_AVAIL` fill policy and an ad break in progress at the end of the avail suppression period**  
When the **avail suppression mode** is set to `AFTER_LIVE_EDGE` and the **avail suppression value** is greater than zero, MediaTailor doesn't personalize any ad breaks until the elapsed time of the session has reached that value.  
In the following figure, various blocks are arranged horizontally along a timeline that progresses from left to right. Each block represents a portion of time where the content of the live stream, a personalized ad break, or a non-personalized ad break plays. A dotted line represents the current live edge of the live stream. Another dotted line, representing the avail suppression value set to `00:30:00`, occurs 30 minutes later in the timeline with respect to the dotted line for the live edge. A third dotted line, representing the session initialization, occurs earlier in the timeline with respect to the dotted line for the live edge. The 30-minute time period between the live-edge time and the avail-suppression-value time represents the avail suppression period. An ad break is in progress at the end of the avail suppression period. As shown in the figure, when the avail suppression mode is set to `AFTER_LIVE_EDGE`, the avail suppression value is set to `00:30:00` after the live edge, the avail suppression fill policy is set to `PARTIAL_AVAIL`, and the session initialization occurs before the live edge, MediaTailor personalizes any ad breaks that occur *after* the avail suppression period. For the ad break in progress at the end of the avail suppression period, MediaTailor personalizes the portion of that ad break which occurs *after* the avail suppression period, but doesn't personalize the portion of that ad break which occurs *during* the avail suppression period.  

![\[MediaTailor ad break personalization with avail suppression mode set to AFTER_LIVE_EDGE, avail suppression value set to 00:30:00, avail suppression fill policy set to PARTIAL_AVAIL, session initialization occurring before the live edge, and an ad break in progress at the end of the avail suppression period.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/ad_supp_after_ending_ad_break.png)


**Example 6: `AFTER_LIVE_EDGE` ad suppression with `PARTIAL_AVAIL` fill policy and an ad break in progress from before session initialization to after the end of the avail suppression period**  
When the **avail suppression mode** is set to `AFTER_LIVE_EDGE` and the **avail suppression value** is greater than zero, MediaTailor doesn't personalize any ad breaks until the elapsed time of the session has reached that value.  
In the following figure, various blocks are arranged horizontally along a timeline that progresses from left to right. Each block represents a portion of time where the content of the live stream, a personalized ad break, or a non-personalized ad break plays. A dotted line represents the current live edge of the live stream. Another dotted line, representing the avail suppression value set to `00:30:00`, occurs 30 minutes later in the timeline with respect to the dotted line for the live edge. A third dotted line, representing the session initialization, occurs earlier in the timeline with respect to the dotted line for the live edge. The 30-minute time period between the live-edge time and the avail-suppression-value time represents the avail suppression period. An ad break is in progress from a time before session initialization to a time after the avail suppression period. As shown in the figure, when the avail suppression mode is set to `AFTER_LIVE_EDGE`, the avail suppression value is set to `00:30:00` after the live edge, the avail suppression fill policy is set to `PARTIAL_AVAIL`, and the session initialization occurs before the live edge, MediaTailor personalizes any ad breaks that occur *after* the avail suppression period. For the ad break in progress before, during, and after the avail suppression period, MediaTailor personalizes the portion of that ad break which occurs *after* the avail suppression period, but doesn't personalize the portion of that ad break which occurs *before* or *during* the avail suppression period.  

![\[MediaTailor ad break personalization with avail suppression mode set to AFTER_LIVE_EDGE; avail suppression value set to 00:30:00; avail suppression fill policy set to PARTIAL_AVAIL; session initialization occurring before the live edge; and an ad break in progress before, during, and after the avail suppression period.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/ad_supp_after_ad_break_throughout.png)


**Example 7: `AFTER_LIVE_EDGE` ad suppression with an ad break in progress at the beginning of the avail suppression period**  
When the **avail suppression mode** is set to `AFTER_LIVE_EDGE` and the **avail suppression value** is greater than zero, MediaTailor doesn't personalize any ad breaks until the elapsed time of the session has reached that value.  
In the following figure, various blocks are arranged horizontally along a timeline that progresses from left to right. Each block represents a portion of time where the content of the live stream or a non-personalized ad break plays. A dotted line represents the current live edge of the live stream. Another dotted line, representing the avail suppression value set to `00:30:00`, occurs 30 minutes later in the timeline with respect to the dotted line for the live edge. A third dotted line, representing the session initialization, occurs earlier in the timeline with respect to the dotted line for the live edge. The 30-minute time period between the live-edge time and the avail-suppression-value time represents the avail suppression period. An ad break is in progress from a time before session initialization to a time within the avail suppression period. As shown in the figure, when the avail suppression mode is set to `AFTER_LIVE_EDGE`, the avail suppression value is set to `00:30:00` after the live edge, and the session initialization occurs before the live-edge time but after the start of the ad break, MediaTailor doesn't personalize that ad break.  

![\[MediaTailor ad break personalization with avail suppression mode set to AFTER_LIVE_EDGE; avail suppression value set to 00:30:00; session initialization occurring before the live edge; and an ad break in progress before but ending during the avail suppression period.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/ad_supp_after_beginning_ad_break.png)


#### Configuring ad suppression parameters – playback session request
<a name="configuring-ad-suppression-parameters-playback-session-request"></a>

You can configure ad suppression settings via parameters in your *initial* server-side or client-side playback session request to MediaTailor. If you've already configured ad suppression settings via the MediaTailor Console or AWS Elemental MediaTailor API, these parameters override those settings.

Both the avail suppression mode and avail suppression value are required for ad suppression to work. These parameters can't be configured from different sources. For example, you can't configure one parameter with the MediaTailor console and another with a query parameter.

MediaTailor supports the following ad suppression parameters.


| Name | Description | Accepted Values | 
| --- | --- | --- | 
| availSuppressionMode |  Sets the mode for ad suppression. By default, ad suppression is `OFF`. When set to `BEHIND_LIVE_EDGE`, MediaTailor doesn't fill ad breaks on or behind the `aws.availSuppressionValue` time. When set to `AFTER_LIVE_EDGE`, MediaTailor doesn't fill ad breaks on or behind the avail suppression period. The avail suppression period spans from the live-edge time to the `aws.availSuppressionValue` time, plus additional buffer time.  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/ad-rules.html)  | 
| availSuppressionValue | A time relative to the live edge in a live stream. | A UTF-8 URL-encoded time code in HH:MM:SS. For example, 1 hour and 30 minutes would be 01%3A30%3A00. | 
| availSuppressionFillPolicy | Defines the policy to apply to the avail suppression mode. BEHIND\$1LIVE\$1EDGE always uses the full avail suppression policy. AFTER\$1LIVE\$1EDGE can be used to invoke partial ad break fills when a session starts mid-break. |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/ad-rules.html)  | 

##### Server-side configuration
<a name="server-side-query"></a>

The base query parameter is `aws.availSuppression`, which is followed by optional parameter name and value pairs. To construct the query, append `aws.availSuppression=` to the end of the playback session request to MediaTailor, followed by parameter names and values. For more information about how to construct a server-side playback session request, see [MediaTailor server-side ad tracking and reporting](ad-reporting-server-side.md).

**Example**: HLS

```
GET <mediatailorURL>/v1/master/<hashed-account-id>/<origin-id>/index.m3u8?aws.availSuppressionMode=BEHIND_LIVE_EDGE&aws.availSuppressionValue=00%3A00%3A21
```

Server-side query syntax is listed in the following table.


| Query String Component | Description | 
| --- | --- | 
| ? | A restricted character that marks the beginning of a query. | 
| aws. | The base query, which is followed by parameters constructed of name and value pairs. For a list of all of the available parameters, see [Configuring ad suppression parameters – playback session request](#configuring-ad-suppression-parameters-playback-session-request).  | 
| = | Associates the parameter name with a value. For example, aws.availSuppressionMode=BEHIND\$1LIVE\$1EDGE. | 
| & | Concatenates query parameters. For example, aws.availSuppressionMode=BEHIND\$1LIVE\$1EDGE&aws.availSuppressionValue=00:30:00&aws.availSuppressionFillPolicy=FULL\$1AVAIL\$1ONLY>. | 

##### Client-side configuration
<a name="client-side-configuration"></a>

Include `availSuppression` parameters in your client's POST request to MediaTailor. For more information about how to construct a client-side playback session request, see [Client-side ad tracking](ad-reporting-client-side.md).

**Example**: HLS

```
POST parent.m3u8
    {
       "availSuppression": {
          "mode": "BEHIND_LIVE_EDGE",
          "value": "00:00:21",
          "fillPolicy": "FULL_AVAIL_ONLY"
       }
    }
```

# MediaTailor bumper ad insertion
<a name="bumpers"></a>

Bumpers are short, non-skippable video or audio clips that play at the start or before the end of an ad break with AWS Elemental MediaTailor.

 The following conditions apply to bumpers: 
+ Bumpers must be 10 seconds or less.
+ Bumpers can be inserted at the start of an ad break, directly before the end of an ad break, or both.
+ Bumpers play during every ad break in a playback session unless pre-roll is configured. If pre-roll is configured, bumpers won't play during the pre-roll break. Instead, they will play in every subsequent break after the pre-roll.
+ For HLS, you must include the `duration` attribute with each SCTE-35 `EXT-X-CUE-OUT` tag.
+ Bumpers are transcoded to match source content.
+ You are not charged for bumpers.

## Configuring bumpers
<a name="configuring-bumpers"></a>

To use bumpers, configure the bumper URLs with the MediaTailor console, MediaTailor API, or the AWS Command Line Interface (AWS CLI). You can configure a start bumper, an end bumper, or both. Bumpers are stored on a server, such as Amazon Simple Storage Service (Amazon S3). The bumper URLs indicate the location of the stored bumper asset(s).

Example start and end bumper URLs:

Start bumper URL: `https://s3.amazonaws.com/startbumperad`

End bumper URL: `https://s3.amazonaws.com/endbumperad`

### Example
<a name="example"></a>

The following is an example of bumper ad behavior.

**Example 1: Start and end bumpers**  
In this example, start and end bumpers are enabled. The ad decision server has 50 seconds of personalized ads to fill a 70-second ad break. The 10-second start bumper plays at the start of the ad break, 50 seconds of ads plays, then the 10-second end bumper.

![\[This illustration shows an ad break filled with a start and end bumper and ads.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/bumpers.png)


# MediaTailor pre-roll ad insertion
<a name="ad-behavior-preroll"></a>

**Note**  
Configurable pre-roll ads are only available for live workflows. For details about how ad insertion (including pre roll) works for VOD, see [Ad stitching behavior for VOD](ad-behavior.md#ad-behavior-vod).

AWS Elemental MediaTailor can insert ads at the beginning of a playback session, before the main content begins. These are *pre-roll* ads.

To insert pre-roll ads, complete the **Live pre-roll ad decision server** and **Live pre-roll maximum allowed duration** fields in the **Additional** settings on your configuration, as described in [Optional configuration settings](configurations-create.md#configurations-create-addl). 

1. When MediaTailor receives a playback request, it sends a request to the ADS for pre-roll ads based on the following fields in the MediaTailor playback configuration:
   + **Live pre-roll ad decision server** is the ad decision server (ADS) URL where MediaTailor sends the request for pre-roll ads. 
   + **Live pre-roll maximum allowed duration** is the total maximum length of time for the pre-roll ads. MediaTailor takes the following action based on the maximum allowed duration:
     + If the total duration of the ads in the ADS response is *less* than the value you gave in **Live pre-roll maximum allowed duration**, MediaTailor inserts all of the ads. When the last ad is complete, MediaTailor immediately returns to the underlying content.
     + If the total duration of the ads in the ADS response is *more* than the value you gave in **Live pre-roll maximum allowed duration**, MediaTailor selects a set of ads that fit into the duration without going over. MediaTailor inserts these ads without clipping or truncation. MediaTailor returns to the underlying content when the last selected ad completes.

1. When MediaTailor receives the pre-roll response from the ADS, it manipulates the manifest to add links to the pre-roll ads. MediaTailor calculates the start time of the pre-roll ad break as follows:
   + For DASH, the formula is `(publishTime - availabilityStartTime) - max(suggestedPresentationDelay, minBufferTime)`.
   + For HLS, the formula is `max(2*EXT-X-TARGETDURATION, EXT-X-START:TIMEOFFSET)`.

1. MediaTailor determines what action to take on any ad breaks that aren't pre-rolls. If the pre-roll overlaps another ad break, MediaTailor doesn't personalize the overlapped portion of the ad break. 

# MediaTailor slate ad insertion
<a name="slate-management"></a>

**Note**  
Slate is only available for live and live-to-VOD workflows.

With AWS Elemental MediaTailor, you can designate a *slate ad* for ad breaks. A slate is a default MP4 asset that is inserted into a stream, such as a still image or looped video, that plays instead of the live content.

AWS Elemental MediaTailor shows slate during ad breaks in the following specific situations:
+ To fill in time remaining in a break that has not been replaced by personalized ads
+ If the Ad Decision Server (ADS) responds with an empty VAST or VMAP response
+ For error conditions, such as ADS timeout or HTTP 500 error from the ADS
+ If an ad isn't available for insertion by MediaTailor (such as when it hasn't finished transcoding)

If you don't configure a slate, MediaTailor defaults to the underlying content stream when one of the above conditions is met.

## Configuring the slate
<a name="configuring-the-slate"></a>

You designate the slate in the **additional configuration **pane in the [ MediaTailor console](https://console.aws.amazon.com/console/home?nc2=h_ct&src=header-signin). MediaTailor downloads the slate from the URL that you specify, and transcodes it to the same renditions as your content. You can control the maximum amount of time that a slate will be shown through the optional **personalization threshold** configuration in the MediaTailor console. For more information, see [How personalization threshold works](#personalization-threshold-scenarios).

The slate must be a high-quality MP4 asset that contains both audio and video. Configuring the slate is optional for non-VPAID configurations but mandatory for VPAID workflows.

**Note**  
If the server that hosts your slate uses HTTPS, its certificate must be from a well-known certificate authority. It can't be a self-signed certificate. If you use a self-signed certificate, then AWS Elemental MediaTailor can't retrieve and stitch the slate into the manifests from the content origin.

## How personalization threshold works
<a name="personalization-threshold-scenarios"></a>

The personalization threshold defines the maximum duration of underfilled ad time (in seconds) allowed in an ad break. This feature applies specifically to ad replacement in Live and VOD streams, rather than ad insertion, because it relies on an underlying content stream.

The behavior varies based on three scenarios:

1. **When personalization is disabled:**

   1. Slate will be inserted for the full duration of unfilled time

   1. Start/End bumpers will be inserted when configured (for more information, see [MediaTailor bumper ad insertion](bumpers.md))

   1. Ads will be inserted as normal

1. **When personalization is enabled and threshold less than break duration:**

   1. If the unfilled time exceeds the personalization threshold:

      1. MediaTailor abandons personalization of the ad break

      1. The underlying content is shown

      1. No ads, slate, or bumpers are inserted

   1. If the unfilled time is less than the personalization threshold:

      1. Ads and slate are inserted

      1. Bumpers are inserted if configured

1. **When personalization is enabled and threshold greater than break duration:**

   1. Ads will be inserted

   1. Slate will be inserted for any remaining time in the ad break

   1. Bumpers will be inserted if configured

The following table provides detailed behaviors for specific scenarios across both HLS and DASH protocols:


**Detailed behavior matrix**  

| Scenario | Personalization disabled | Personalization enabled less than break duration | Personalization enabled greater than break duration | 
| --- | --- | --- | --- | 
| Empty VAST or VMAP | Slate inserted | No slates inserted | Slate inserted | 
| ADS timeout | Slate inserted | No slates inserted | Slate inserted | 
| Ad isn't available (Vast 404) | Slate inserted | No slates inserted | Slate inserted | 
| Duration of ads is longer than ad break | Ads inserted | No ads inserted | Ads inserted | 
| Fill in time that's not fully used by an ad replacement | Slate inserted | If personalization threshold greater than unfilled time: No ads/slates inserted, else: Ads and slates inserted | Slate inserted | 
| Preroll with empty VAST | Slate inserted, no preroll inserted | No slates inserted, no preroll inserted | Slate inserted, no preroll inserted | 
| Preroll with ADS timeout | Slate inserted, no preroll inserted | No slates inserted, no preroll inserted | Slate inserted, no preroll inserted | 
| Preroll when ad isn't available (Vast 404) | Slate inserted, no preroll inserted | No slates inserted, no preroll inserted | Slate inserted, no preroll inserted | 
| Bumpers with empty VAST | Slate inserted, bumper inserted | No slates inserted, no bumpers inserted | Slate inserted, bumper inserted | 
| Bumpers with ADS timeout | Slate inserted, bumper inserted | No slates inserted, no bumpers inserted | Slate inserted, bumper inserted | 
| Bumpers when ad isn't available (Vast 404) | Slate inserted, bumper inserted | No slates inserted, no bumpers inserted | Slate inserted, bumper inserted | 
| Bumpers to fill in time that's not fully used by ad replacement | Slate inserted, bumper inserted, ad inserted | If personalization threshold greater than unfilled time: No bumpers/ads/slates inserted, else: No bumpers/ads/slates inserted | Slate inserted, bumper inserted, ad inserted | 

**Important considerations**  
Remember the following when you're working with slate and personalization threshold.
+ This behavior is consistent across both HLS and DASH protocols
+ The personalization threshold feature only applies when slate is configured
+ When slate is configured and personalization threshold is not configured, slate will play for either the full origin avail duration or whatever time remains after filling in the ads
+ For VPAID ads, MediaTailor inserts slate for the duration of the VPAID ad to hold space for ads that the video player will insert

## Slate configuration and VPAID
<a name="vpaid-requirements"></a>

**Important**  
Slate configuration is mandatory when using VPAID ads. MediaTailor inserts slate to hold space for VPAID ads that the video player will insert. The slate duration might be slightly longer than the VPAID ad duration to accommodate user interactivity.

The video player then handles the VPAID ad based on the client-side reporting metadata that MediaTailor returns, as described in [VPAID requirements](vast.md#vpaid). For information about client-side reporting, see [Client-side ad tracking](ad-reporting-client-side.md).

# Prefetching ads
<a name="prefetching-ads"></a>

Use AWS Elemental MediaTailor ad prefetching for live streams to help reduce peak load on ad decision servers (ADS) and decrease manifest delivery latency at the start of each ad break. When you define a prefetch schedule, MediaTailor follows the schedule to retrieve ads from the ADS and prepare them for ad insertion before they’re needed for an ad break. During live streams, prefetching can help mitigate decreased ad fill rates and missed monetization opportunities because of ad request and transcoding timeouts or other network delays. 

**Note**  
Ad prefetching does not work with server-guided ad insertion (SGAI) methods, including traditional server-guided and HLS Interstitials. SGAI methods do not require prefetching because players only fetch ads they are going to play, and manifests can be served by CDNs without MediaTailor seeing individual session requests.

To set up ad prefetching, you create one or more *prefetch schedules* on your playback configuration. A prefetch schedule tells MediaTailor how and when to retrieve and prepare ads for an upcoming ad break. 
+ If an event has ad avails that are on a predictable schedule, use a *single prefetch schedule*. Each single prefetch schedule defines a single set of ads for MediaTailor to place in a single ad avail. To prefetch ads for multiple ad avails when you use single prefetch schedules, you must create multiple prefetch schedules (up to 24 hours before the ad avail) that correlate to each ad avail. 
+ If an event has ad avails that aren't on a predictable schedule, use a *recurring prefetch schedule*. A recurring prefetch schedule automatically creates a schedule and prefetches ads before each ad break in an event. The recurring prefetch schedule retrieves ads for every ad avail within a defined period of time (up to 24 hours before the event ends). You don’t need to create a schedule for each ad avail, but you do lose some of the timing control that single prefetch offers.

The following topics describe more about ad prefetching.

**Topics**
+ [How prefetching works](understanding-prefetching.md)
+ [Creating prefetch schedules](creating-prefetch-schedules.md)
+ [TPS-based traffic shaping](tps-traffic-shaping.md)
+ [Deleting prefetch schedules](deleting-prefetch-schedules.md)

# How prefetching works
<a name="understanding-prefetching"></a>

When your client makes a manifest request to MediaTailor, the service evaluates all of the prefetch schedules that are associated with the playback configuration. If MediaTailor doesn't find a matching prefetch schedule, the service reverts to normal ad insertion and doesn't prefetch ads.

If MediaTailor finds a matching prefetch schedule, the service evaluates the schedule based on two components: retrieval and consumption. The configuration of each component varies between single prefetch schedules and recurring prefetch schedules, as described in the following sections.

## Single prefetch schedule flow
<a name="understanding-prefetching-single"></a>

**Retrieval**  
This defines the *retrieval window*, which is the time range when MediaTailor prefetches ads from the ADS. Be sure to schedule this window for a time that's before the ad break. The following provides an overview of how MediaTailor processes a single prefetch schedule.  
For steps to create a single prefetch schedule in the console, see [Creating prefetch schedules](creating-prefetch-schedules.md). For API instruction, see [PrefetchSchedules](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_PrefetchSchedule.html) in the *AWS Elemental MediaTailor API Reference*.  
During the specified *retrieval window*, MediaTailor sends requests to the ADS to retrieve and prepare ads for later insertion in playback sessions.  
+ MediaTailor optionally uses traffic shaping to limit the number of requests to the ADS at one time. You can choose between two approaches:

  *Time-window traffic shaping* - MediaTailor spreads requests across the specified number of seconds instead of sending requests for all sessions at one time. This dispersed traffic distribution helps to prevent the ADS from becoming overwhelmed, resulting in time outs and low ad fill rates.

  *TPS-based traffic shaping* - MediaTailor limits requests based on transactions per second (TPS) and concurrent users. This approach provides more intuitive configuration based on your ADS capacity limits. For more information, see [TPS-based traffic shaping](tps-traffic-shaping.md).
+ If you set up *dynamic variables*, MediaTailor includes these variables in the requests to the ADS. MediaTailor uses these variables to match ad avails to prefetch schedules during the consumption window. See the following *Consumption* section for more information.

**Example**  
A live event lasts from 7:45AM to 10AM, with an ad break at 8:15AM. You configure MediaTailor to retrieve ads from 7:45AM to 8AM, with a traffic shaping window of 60 seconds. With 500,000 concurrent users, MediaTailor distributes the ADS requests to achieve an average rate of approximately 8,333 transactions per second for 60 seconds (500,000 users/60 seconds=8,333 requests per second), instead of sending all requests simultaneously.   
The retrieval configuration includes the dynamic variable key `scte.event` and value `1234`. MediaTailor includes this variable in the requests to the ADS, which then can be used to target specific advertisers to the event ID 1234. 

**Consumption**  
When MediaTailor encounters SCTE-35 ad break markers during the consumption window, it places the prefetched ads in an ad break.  
+ If you didn’t set avail matching criteria, MediaTailor inserts ads in the first break in the consumption window.
+ If you did set a *dynamic variable key* for *avail* *matching* *criteria*, MediaTailor evaluates these criteria against the dynamic variables that you set in the retrieval window. An ad break is eligible for prefetched ad insertion only if the avail matching criteria are met. MediaTailor inserts ads in the first break that meets the criteria.

  For a list of supported avail-matching criteria, see the *Available for ad prefetch* column in the table on [MediaTailor session variables for ADS requests](variables-session.md).

**Example continued**  
You set the start time for consumption as 8:15AM, and the end time as 8:17AM. You include `scte.event_id` for the key in the avail matching criteria.   
For each ad break that MediaTailor encounters from 8:15AM to 8:17AM, it evaluates the SCTE event ID for each ad break. In each playback session, MediaTailor inserts the prefetched ads in the first ad break that has an event ID of 1234 (as defined in the retrieval dynamic variables). For ad breaks that don’t contain the correct event ID, MediaTailor performs standard ad insertion. 

## Recurring prefetch schedule flow
<a name="understanding-prefetching-recurring"></a>

**Retrieval**  
This defines the *recurring retrieval window*, which is the time range when MediaTailor prefetches and inserts ads for a live event (up to 24 hours). The following provides an overview of how MediaTailor processes recurring prefetch schedules.  
For steps to create a recurring prefetch schedule in the console, see [Creating prefetch schedules](creating-prefetch-schedules.md). For API instruction, see [PrefetchSchedules](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_PrefetchSchedule.html) in the *AWS Elemental MediaTailor API Reference*.  
During the specified recurring prefetch window, MediaTailor retrieves and inserts ads for a live event that’s up to 24 hours. After each ad break in the window, MediaTailor automatically retrieves ads for the next ad break.   
+ If you set the *delay after avail end*, MediaTailor waits the specified time before retrieving the next set of ads for the next ad break.
+ MediaTailor optionally uses traffic shaping to limit the number of requests to the ADS at one time. You can choose between two approaches:

  *Time-window traffic shaping* - MediaTailor spreads requests across the specified number of seconds instead of sending requests for all sessions at one time. This dispersed traffic distribution helps to prevent the ADS from becoming overwhelmed, resulting in time outs and low ad fill rates.

  *TPS-based traffic shaping* - MediaTailor limits requests based on transactions per second (TPS) and concurrent users. This approach provides more intuitive configuration based on your ADS capacity limits. For more information, see [TPS-based traffic shaping](tps-traffic-shaping.md).
+ If you set up *dynamic variables*, MediaTailor includes these variables in the requests to the ADS. MediaTailor uses these variables to match ad avails to prefetch schedules during the consumption window. See the following *Consumption* section for more information.

**Example**  
A live event lasts from 7PM to 8:45PM, with four ad breaks over that time. The ad breaks aren’t on a predictable schedule. You configure the recurring prefetch from 7PM to 8:45PM, with a 10 minute delay and traffic shaping window of 60 seconds. After each avail, MediaTailor retrieves ads for the next ad break. Ten minutes after the avail ends, MediaTailor starts to send retrieval requests to the ADS. With a 60-second traffic-shaping window and 500,000 concurrent users, MediaTailor distributes the ADS requests to achieve an average rate of approximately 8,333 transactions per second for 60 seconds (500,000 users/60 seconds=8,333 requests per second), instead of sending all requests simultaneously.   
The retrieval configuration includes the dynamic variable key `scte.event` and value `1234`. MediaTailor includes this variable in the requests to the ADS, which then can be used to target specific advertisers to the event ID 1234.

**Consumption**  
When MediaTailor encounters SCTE-35 ad break markers, it places the prefetched ads in an ad break.  
+ If you set the *retrieved ad expiration*, prefetched ads are available for insertion until the specified expiration.
+ If you didn’t set avail matching criteria, MediaTailor inserts ads in the first break in the consumption window.
+ If you did set a *dynamic variable key* for *avail* *matching* *criteria*, MediaTailor evaluates these criteria against the dynamic variables that you set in the retrieval window. An ad break is eligible for prefetched ad insertion only if the avail matching criteria are met. MediaTailor inserts ads in the first break that meets the criteria.

  For a list of supported avail-matching criteria, see the *Available for ad prefetch* column in the table on [MediaTailor session variables for ADS requests](variables-session.md).

**Example continued**  
In the consumption, you include `scte.event_id` for the key in the avail matching criteria.   
For each ad break that MediaTailor encounters, it evaluates the SCTE event ID for each ad break. In each playback session, MediaTailor inserts the prefetched ads in each ad break that has an event ID of 1234 (as defined in the retrieval dynamic variables). For ad breaks that don’t contain the correct event ID, MediaTailor performs standard ad insertion.   
You set the ad expiration to 2700 seconds so retrieved ads are available for insertion for 45 minutes.
The following graphic illustrates the example, with the small squares representing ad breaks. The recurring prefetch schedule settings are illustrated along the event timeline.  

![\[Graphical illustration of a live event including recurring prefetch schedule configurations.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/recurring_prefetch_timeline.png)


## Understanding prefetching costs
<a name="billing"></a>

There are no costs for making ad retrieval requests. However, for prefetch ad retrieval, you'll be charged at the standard transcoding rate for the prefetched ads that MediaTailor transcodes. For prefetch ad consumption, you'll be charged at the standard rate for ad insertion for the prefetched ads that MediaTailor places in ad breaks. For information about transcoding and ad insertion costs, see [AWS Elemental MediaTailor Pricing](https://aws.amazon.com/mediatailor/pricing/).

# Creating prefetch schedules
<a name="creating-prefetch-schedules"></a>

The following procedure explains how to create a prefetch schedule by using the MediaTailor console. For information about creating and managing prefetch schedules programmatically using the MediaTailor API, see [PrefetchSchedules](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_PrefetchSchedule.html) in the *AWS Elemental MediaTailor API Reference*.

**Note**  
When configuring prefetch schedules in MediaTailor, it's important to understand how different types of variables are handled.  

**Avail matching criteria**  
If you want to use avail matching criteria in a schedule, make sure that you first configure your playback configuration's ADS URL template with [dynamic session variables](variables-session.md), otherwise the avail matching criteria won't have an effect. For information about working with dynamic session variables, see [Step 3: Configure ADS request URL and query parameters](getting-started-ad-insertion.md#getting-started-configure-request) in the Getting started with MediaTailor ad insertion topic.

**Player variables in prefetch schedules**  
When you create a prefetch schedule, don't define player variables as dynamic variables in your prefetch configuration. Instead, pass the player variables as you normally would at session start. MediaTailor automatically includes these variables in prefetch ad requests if the variables are mapped in the ADS template URL.

**To create a new prefetch schedule using the console**

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

1. In the navigation pane, choose **Configurations**. Select the playback configuration that you want to create a prefetch schedule for.

1. On the **Prefetch schedules** tab, choose **Add prefetch schedule**.

1. Under the **Prefetch schedule details** pane, do the following:
   + For **Name**, enter an identifier for your prefetch schedule, such as **my-prefetch-schedule**.
   + For **Stream ID**, optionally enter a unique ID. If your origin contains multiple playback streams, you can use this ID to instruct MediaTailor to place ads in a specific stream. For example, if your playback configuration has a sports stream and a TV show stream, you can use the stream ID to create prefetch schedules to insert ads targeted for the sports stream. You pass the stream ID value to MediaTailor in your client's session initialization or manifest request. For more information see the following example.
     + For *server-side tracking*, include the `?aws.streamId` query parameter and value in your client's `GET HTTP` request to your MediaTailor endpoint. For general information about server-side tracking see [MediaTailor server-side ad tracking and reporting](ad-reporting-server-side.md). A manifest request to an HLS endpoint that includes a stream ID looks like the following, where `myStreamId` is the name of your stream ID:

       ```
       GET <mediatailorURL>/v1/master/<hashed-account-id>/<origin-id>/<asset-id>?aws.streamId=myStreamId
       ```
     + For *client-side tracking*, include the `streamId` key and value in your client's `POST HTTP` session initialization request body to the **MediaTailor/v1/session** endpoint. For general information about client-side tracking see [Client-side ad tracking](ad-reporting-client-side.md). A session initialization request that includes a stream ID looks like the following, where `myStreamId` is the name of your stream ID:

       ```
       POST <mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>
       {
           'streamId': 'myStreamId',
           'reportingMode': 'client'
       }
       ```

1. For **Prefetch type**, make your selection and choose the corresponding section for assistance with additional fields:
   + Choose **Single** if you're creating one prefetch schedule for one ad break in an event.
   + Choose **Recurring** if you're creating a schedule that automatically prefetches ads before each ad break in an event. 

## Single prefetch schedule
<a name="single-prefetch"></a>

To create a schedule that prefetches ads before one ad avail in an event.

1. On the **Retrieval** pane, specify the retrieval settings you want to use. These settings determine when MediaTailor prefetches ads from the ADS. They also determine which dynamic session variables to include in the request to the ADS, if any.
   + For **Start time**, enter the time when MediaTailor can start prefetch retrievals for this ad break. MediaTailor will attempt to prefetch ads for manifest requests made by your client on or after this time. The default value is the current time. If you don't specify a value, the service starts prefetch retrieval as soon as possible.
   + For **End time**, enter the time when you want MediaTailor to stop prefetching ads for this ad break. MediaTailor will attempt to prefetch ads for manifest requests that occur at or before this time. The retrieval window can overlap with the consumption window.
   + Optionally, configure traffic shaping to limit the number of requests to the ADS at one time. Choose one of the following approaches:

     *Time-window approach*: For **Traffic shaping window duration**, enter the number of seconds that MediaTailor should distribute requests to the ADS. For more information, see [Single prefetch schedule retrieval explanation](understanding-prefetching.md#avail-matching-criteria-retr).

     *TPS-based approach*: Configure **Peak TPS** and **Peak concurrent users** to limit requests based on transactions per second and concurrent users. For more information, see [TPS-based traffic shaping](tps-traffic-shaping.md).
   + In the [**Dynamic variables**](variables.md) section, enter as many as 100 dynamic session variables. MediaTailor uses these variables for substitution in prefetch requests that it sends to the ADS. If you don't enter any dynamic session variables, MediaTailor makes a best effort attempt to interpolate the values for the dynamic variables contained in your [ADS](configurations-create.md#configurations-create-main) URL.
     + Select **Add dynamic variable**. 
     + For **Key**, enter a dynamic session variable key, such as `scte.event_id`. You can use any dynamic variable that MediaTailor supports. For information about dynamic session variables, see [MediaTailor session variables for ADS requests](variables-session.md).
     + For **Value**, enter a dynamic variable value, such as *my-event*.
     + To add another dynamic variable, choose Select **Add dynamic variable**. 

1. On the **Consumption** pane, specify the settings that you want to use for the consumption window. These settings determine when MediaTailor places the ads into the ad break. They also determine any avail matching criteria that you want to use.
   + For **Start time**, enter the time when you want MediaTailor to begin to place prefetched ads into the ad break. the default value is the current time. If you don't specify a time, the service starts prefetch consumption as soon as possible.
   + For **End time**, enter a time when you want MediaTailor to stop placing the prefetched ads into the ad break. MediaTailor will attempt to prefetch ads for your client's manifest requests that occur at or before this time. The end time must be after the start time, and less than one day from now. The consumption window can overlap with the retrieval window.
   + In the [**Avail matching criteria**](variables.md) section, select **Add avail criteria** and add as many ad five avail matching criteria to your schedule. Then, under **Dynamic variable key**, add a dynamic variable key, such as `scte.event_id`. MediaTailor will place the prefetched ads into the ad break *only* if it meets the criteria defined by the dynamic variable values that either your client passes to MediaTailor, or that MediaTailor infers from information such as session data. If an ad break doesn't meet the specified matching criteria, MediaTailor skips the prefetch for that break. For information, see the [Single prefetch schedule consumption explanation](understanding-prefetching.md#avail-matching-criteria).

1. Select **Add avail criteria**.

Prefetch schedules automatically expire after the consumption window's end time. For diagnostic purposes, they remain visible for at least 7 days, after which MediaTailor automatically deletes them. Alternatively, you can manually delete a prefetch schedule at any time. For information about how to manually delete a prefetch schedule, see the following [Deleting prefetch schedules](deleting-prefetch-schedules.md) section.

### Determining how often your client should call the CreatePrefetchSchedule API
<a name="how-often"></a>

Your client can programmatically call the [CreatePrefetchSchedule](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_CreatePrefetchSchedule.html) API once per day to set up retrieval and consumption if you have knowledge of exactly when ad breaks will occur. Or, your client can call the API many times over the course of the day to define retrieval and consumption. When choosing an API call frequency, take into consideration the [maximum number of active prefetch schedules](quotas.md#prefetch-schedules-limit), and the likelihood of whether your ad break schedule will change after you create your prefetch schedule(s). If it's likely that the ad break schedule will change after you've created your prefetch schedule(s), you might want to call the API more frequently.

## Recurring prefetch schedule
<a name="recurring-prefetch"></a>

To create a schedule that prefetches ads before each ad avail in an event.

1. On the **Recurring retrieval** pane, specify the retrieval settings you want to use. These settings determine when MediaTailor prefetches ads from the ADS. They also determine which dynamic session variables to include in the request to the ADS, if any.
   + For **Recurring prefetch window**, enter the time when MediaTailor can start prefetch retrievals for this ad break. MediaTailor will attempt to prefetch ads for manifest requests made by your client on or after this time. The default value is the current time. If you don't specify a value, the service starts prefetch retrieval as soon as possible.
   + For **Delay after avail end**, enter the number of seconds that MediaTailor should wait after an avail ends before prefetching ads for the next avail. If you don't specify a value, MediaTailor defaults to a no delay. 
   + Optionally, configure traffic shaping to limit the number of requests to the ADS at one time. Choose one of the following approaches:

     *Time-window approach*: For **Traffic shaping window duration**, enter the number of seconds that MediaTailor should distribute requests to the ADS. For more information, see [Recurring prefetch schedule retrieval explanation](understanding-prefetching.md#avail-matching-criteria-recurring-retr)

     *TPS-based approach*: Configure **Peak TPS** and **Peak concurrent users** to limit requests based on transactions per second and concurrent users. For more information, see [TPS-based traffic shaping](tps-traffic-shaping.md).
   + In the [**Dynamic variables**](variables.md) section, enter as many as 100 dynamic session variables. MediaTailor uses these variables for substitution in prefetch requests that it sends to the ADS. If you don't enter any dynamic session variables, MediaTailor makes a best effort attempt to interpolate the values for the dynamic variables contained in your [ADS](configurations-create.md#configurations-create-main) URL.
     + Select **Add dynamic variable**. 
     + For **Key**, enter a dynamic session variable key, such as `scte.event_id`. You can use any dynamic variable that MediaTailor supports. For information about dynamic session variables, see [MediaTailor session variables for ADS requests](variables-session.md).
     + For **Value**, enter a dynamic variable value, such as *my-event*.
     + To add another dynamic variable, choose Select **Add dynamic variable**. 

1. On the **Consumption** pane, specify the settings that you want to use for the consumption window. These settings determine when MediaTailor places the ads into the ad break. They also determine any avail matching criteria that you want to use.
   + For **Retrieved ad expiration**, indicate how long after retrieval ads are available for insertion.
   + In the [**Avail matching criteria**](variables.md) section, select **Add avail criteria** and add as many ad five avail matching criteria to your schedule. Then, under **Dynamic variable key**, add a dynamic variable key, such as `scte.event_id`. MediaTailor will place the prefetched ads into the ad break *only* if it meets the criteria defined by the dynamic variable values that either your client passes to MediaTailor, or that MediaTailor infers from information such as session data. If an ad break doesn't meet the specified matching criteria, MediaTailor skips the prefetch for that break. For information, see the [Recurring prefetch schedule consumption explanation](understanding-prefetching.md#avail-matching-criteria-recur).

1. Select **Add avail criteria**.

Prefetch schedules automatically expire after the consumption window's end time. For diagnostic purposes, they remain visible for at least 7 days, after which MediaTailor automatically deletes them. Alternatively, you can manually delete a prefetch schedule at any time. For information about how to manually delete a prefetch schedule, see the following [Deleting prefetch schedules](deleting-prefetch-schedules.md) section.

# TPS-based traffic shaping
<a name="tps-traffic-shaping"></a>

AWS Elemental MediaTailor provides two optional traffic shaping approaches to limit the number of requests to the ADS at one time. TPS-based traffic shaping offers an alternative to time-window based traffic shaping for prefetch schedules. This approach provides more intuitive configuration by allowing you to specify your ad decision server (ADS) capacity in terms of transactions per second (TPS) and expected concurrent users, rather than time calculations.

## How TPS-based traffic shaping works
<a name="tps-how-it-works"></a>

Instead of specifying retrieval window durations, you provide the following parameters:

Peak TPS  
The maximum number of requests per second that your ADS can handle. This parameter has no default value.

Peak concurrent users  
The expected peak number of concurrent viewers for your content. This parameter has no default value.

MediaTailor automatically distributes prefetch requests across time to stay within your specified TPS limit, regardless of the number of concurrent sessions.

**Example TPS-based configuration example**  
Your ADS can handle 500 TPS, and you expect 100,000 concurrent viewers during peak times. You configure:  
+ Peak TPS: 500
+ Peak concurrent users: 100,000
MediaTailor automatically distributes prefetch requests across time to stay within your specified TPS limit, regardless of the number of concurrent sessions.

# Deleting prefetch schedules
<a name="deleting-prefetch-schedules"></a>

The following procedure explains how to delete a prefetch schedule by using the MediaTailor console. For information about how to delete prefetch schedules programmatically using the MediaTailor API, see [DeletePrefetchSchedule](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_DeletePrefetchSchedule.html) in the *AWS Elemental MediaTailor API Reference*.

**Note**  
Deletion doesn't occur in real time. You might experience a delay while MediaTailor deletes the prefetch schedule(s), during which time prefetch retrieval and consumption will continue to run in the background.

**To delete a prefetch schedule using the console**

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

1. In the navigation pane, choose **Configurations**. Select the playback configuration that contains the prefetch schedule(s) that you want to delete.

1. On the **Prefetch schedules** tab, select the prefetch schedule that you want to delete. Then, choose **Delete**.

# Using preconditioned ads with AWS Elemental MediaTailor
<a name="precondition-ads"></a>

In a [typical ad insertion workflow](what-is-flow.md), MediaTailor dynamically transcodes ads to match the content stream, saves them, and stitches the ads into the live stream. Because this process happens only after MediaTailor receives the ad in a VAST response from the ad decision server (ADS), there is a delay for when the ad is available for stitching. If additional latency is introduced to the ad stitching workflow (either because of ADS timeout or other content or network issues), MediaTailor could partially fill the avail, or miss the ad break altogether. 

To reduce the time needed to stitch ads into your content, you can use preconditioned ads. A preconditioned ad is one that you transcode before using it in MediaTailor ad insertion. Instead of providing URLs for the unconditioned ads to your ADS, you provide the URLs for the preconditioned ads. In its VAST response to the MediaTailor request, the ADS includes direct links to the preconditioned ads. By removing the transcoding part of ad stitching, MediaTailor needs to just save the ad and stitch it into the content stream. The ad stitching process with preconditioned ads reduces the time between when MediaTailor is made aware of an ad through the VAST response and when the ad is stitched into the content. 

Alternatively, you can also use ad prefetching, which is when you configure MediaTailor to perform the ad stitching process at a scheduled time before the ad break is needed. For more information about ad prefetching, see [Prefetching ads](prefetching-ads.md).

## Preconditioned ads requirements
<a name="precondition-ads-req"></a>

The following are requirements to consider when setting up an ad stitching workflow with preconditioned ads.

### `MediaFiles` requirements
<a name="precondition-ads-req-vast"></a>

The VAST response that the ad server sends to MediaTailor must include `MediaFiles` that meet these requirements:

The ad (`Creative`) must have variants that conform to the bitrate variants of the content stream.*It's your responsibility to ensure that the VAST response uses the right ad variants to match template manifests. *

While using preconditioned ads can help make ad insertion more efficient, MediaTailor does not have the ability to manage the transcoding process to ensure that the media files for the ads are compatible with the content manifest specifications. If the ad doesn't match the content stream, MediaTailor could miss the insertion or the mismatch could cause the playback device to error. 

Additionally, to be stitched into the content stream without MediaTailor transcoding, a `MediaFile` must meet these requirements:
+ It must be accessible on the public internet so that MediaTailor can download it. 
+ It must use streaming delivery, denoted as `delivery="streaming"` in the VAST response.
+ It must be either a `.m3u8` (for HLS) or `.mpd` (for DASH) file.

**Example VAST response**  
From the following example VAST response, MediaTailor inserts the `MediaFile` with the following URLs:  
+ For an HLS stream, MediaTailor uses `https://example-ad-origin.amazonaws.com/ad1/index_low.m3u8`. This is the first `MediaFile` with streaming delivery and a supported file extension (.`m3u8`).
+ For a DASH stream, MediaTailor uses `https://example-ad-origin.amazonaws.com/ad1/index.mpd`. This is the first `MediaFile` with streaming delivery and a supported file extension (.`mpd`).

```
<?xml version="1.0" encoding="UTF-8"?>
<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="3.0">
    <Ad id="ad1">
        <InLine>
            <AdSystem>ExampleAdSystem</AdSystem>
            <AdTitle>ad1</AdTitle>
            <Impression><![CDATA[https://example-impression.amazonaws.com]]></Impression>
            <AdServingId>de8e0d33-9c72-4d77-bb3a-f7e566ffc605</AdServingId>
            <Creatives>
                <Creative id="creativeId1" sequence="1">
                    <Linear skipoffset="00:00:05">
                        <Duration>00:00:30</Duration>
                        <MediaFiles>
                            <MediaFile delivery="progressive" width="1280" height="720" type="video/mp4" bitrate="533" scalable="true" maintainAspectRatio="true"><![CDATA[https://example-ad-origin.amazonaws.com/ad1/ad1.mp4]]></MediaFile>
                            <MediaFile delivery="streaming" width="1280" height="720" type="application/dash+xml" bitrate="533" scalable="true" maintainAspectRatio="true"><![CDATA[https://example-ad-origin.amazonaws.com/ad1/index.mpd]]></MediaFile>
                            <MediaFile delivery="streaming" width="640" height="360" type="application/x-mpegURL" bitrate="262" scalable="true" maintainAspectRatio="true"><![CDATA[https://example-ad-origin.amazonaws.com/ad1/index_low.m3u8]]></MediaFile>
                            <MediaFile delivery="streaming" width="2560" height="1440" type="application/x-mpegURL" bitrate="1066" scalable="true" maintainAspectRatio="true"><![CDATA[https://example-ad-origin.amazonaws.com/ad1/index_high.m3u8]]></MediaFile>
                        </MediaFiles>
                    </Linear>
                </Creative>
            </Creatives>
        </InLine>
    </Ad>
</VAST>
```

### Ad manifest requirements
<a name="precondition-ads-req-ads"></a>

To use preconditioned ads, your parent and child ad manifests must meet these requirements:
+ The manifest that's linked in the `Creative` section of the VAST response must be the parent ad manifest.
+ The URLs for the child ad manifests must be relative paths.
+ The child ad manifests must be in the same directory as the parent multivariant playlist, at the same level. Child manifests can't be in a sub-directory or other location.

**Example supported parent multivariant playlist**  
The following parent ad multivariant playlist contains relative URLs for child ad media playlists. The child playlists are also in the same directory as the parent multivariant playlist.  

```
#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=150000,RESOLUTION=416x234,CODECS="avc1.42e00a,mp4a.40.2"
index_1.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=440000,RESOLUTION=416x234,CODECS="avc1.42e00a,mp4a.40.2"
index_2.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=640000,RESOLUTION=640x360,CODECS="avc1.42e00a,mp4a.40.2"
index_3.m3u8
```

**Example unsupported parent multivariant playlist: subdirectories**  
The following parent ad multivariant playlist contains child playlists that are in sub-directories relative to the parent multivariant playlist. It is not a supported playlist for preconditioned ads.  

```
#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=150000,RESOLUTION=416x234,CODECS="avc1.42e00a,mp4a.40.2"
child/index_1.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=440000,RESOLUTION=416x234,CODECS="avc1.42e00a,mp4a.40.2"
child/index_2.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=640000,RESOLUTION=640x360,CODECS="avc1.42e00a,mp4a.40.2"
child/index_3.m3u8
```

**Example unsupported parent multivariant playlist: absolute URLs**  
The following parent ad multivariant playlist contains child playlists with absolute URLs. It is not a supported playlist for preconditioned ads.  

```
#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=150000,RESOLUTION=416x234,CODECS="avc1.42e00a,mp4a.40.2"
https://example.mediatailor.us-west-2.amazonaws.com/index_1.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=440000,RESOLUTION=416x234,CODECS="avc1.42e00a,mp4a.40.2"
https://example.mediatailor.us-west-2.amazonaws.com/index_2.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=640000,RESOLUTION=640x360,CODECS="avc1.42e00a,mp4a.40.2"
https://example.mediatailor.us-west-2.amazonaws.com/index_3.m3u8
```

## Preconditioned ads workflow
<a name="precondition-ads-setup"></a>

The following is a basic description of how preconditioned ads work in an ad stitching workflow with MediaTailor. The first part of the workflow are actions that you must take to get set up for using preconditioned ads. The second part describes how MediaTailor processes the ads.

**Part 1: Preconditioned ads set up**  
Complete the following steps to set up a workflow that uses preconditioned ads in MediaTailor.

1. Use a transcoder service, such as AWS Elemental MediaConvert, to condition your creatives into variants that support the different bitrates, resolutions, and codecs of your template manifests. 

1. Provide the URLs for the pre-transcoded media files to your ADS, for use in VAST responses.

1. [Create your playback](configurations-create.md) configuration in MediaTailor. To use preconditioned ads, select **None** for the **Streaming media file conditioning** setting in the configuration.

1. Continue with your content delivery set up as you normally would.

**Part 2: MediaTailor ad processing**  
MediaTailor ad stitching completes as described in [How MediaTailor ad insertion works](what-is-flow.md). When MediaTailor receives a VAST response from the ADS, it uses the following logic to determine what actions to take for the ads. This logic is dictated by the **Streaming media file conditioning** setting on the playback configuration. 
+ When **Streaming media file conditioning** is set to **Transcode**, MediaTailor transcodes the media files with `progressive` delivery and stitches them into the manifest. If there aren't enough ads with `progressive` delivery media files to fill the avail, MediaTailor transcodes and uses those with `streaming` delivery.
+ When **Streaming media file conditioning** is set to **None**, MediaTailor stitches ads with `streaming` delivery media files into the manifest without transcoding them. If there aren't enough ads with `streaming` delivery media files to fill the avail, MediaTailor transcodes and uses those with `progressive` delivery. 

# MediaTailor dynamic ad variables for ADS requests
<a name="variables"></a>

AWS Elemental MediaTailor uses dynamic ad variables to pass information from your viewing session to the ad decision server (ADS). This information helps the ADS select the most relevant ads for your viewers.

This section provides an overview of dynamic ad variables and links to specific implementation guides. For step-by-step configuration instructions, see the individual topics below.

**Dynamic variable types**  
MediaTailor supports four types of dynamic variables:
+ **Session variables** – Automatically generated values like session ID and SCTE-35 data. See [MediaTailor session variables for ADS requests](variables-session.md).
+ **Player variables** – Custom parameters sent by your video player. See [MediaTailor player variables for ADS requests](variables-player.md).
+ **Domain variables** with **Configuration aliases** – Dynamic URL domains for multi-origin configurations. 
+ **Configuration aliases** – Predefined mappings for dynamic variable replacement. See [Configuration aliases](configuration-aliases-overview.md).

**Common use cases**  
Use dynamic ad variables to:
+ Pass viewer demographics and preferences to your ADS
+ Route requests to different origins based on geographic location
+ Enable time-shifted viewing with MediaPackage integration
+ Implement A/B testing and failover scenarios

The following sections provide additional detail about using dynamic ad variables with MediaTailor.

**Topics**
+ [Session variables](variables-session.md)
+ [Player variables](variables-player.md)
+ [Domain variables](variables-domains.md)
+ [Configuration aliases](configuration-aliases-overview.md)
+ [Passing ADS parameters](passing-paramters-to-the-ads.md)
+ [Parameter routing](parameter-routing-behavior.md)
+ [MediaPackage integration](mediapackage-integration-param.md)
+ [Session behavior](parameter-session-behavior.md)
+ [Parameter reference](parameter-comprehensive-reference.md)
+ [Parameter troubleshooting](parameter-troubleshooting.md)
+ [Alias troubleshooting](configuration-aliases-troubleshooting.md)

For parameter formatting requirements and troubleshooting, see [MediaTailor parameter reference and limitations](parameter-comprehensive-reference.md) and [MediaTailor parameter troubleshooting guide](parameter-troubleshooting.md).

# MediaTailor session variables for ADS requests
<a name="variables-session"></a>

AWS Elemental MediaTailor sends session data to the Ad Decision Server (ADS) when you configure AWS Elemental MediaTailor to specify one or more of the variables listed in this section in the template ADS URL. You can use individual variables, and you can concatenate multiple variables to create a single value. MediaTailor generates some values and obtains the rest from sources like the manifest and the player's session initialization request. 

The following table describes the session data variables you can use in your template ADS request URL configuration. The section numbers listed in the table correspond to the 2019a version of the Society of Cable Telecommunications Engineers (SCTE)-35 specification, [Digital Program Insertion Cueing Message](https://account.scte.org/standards/library/catalog/scte-35-digital-program-insertion-cueing-message/), For details about ad prefetch, see [Prefetching ads](prefetching-ads.md).


| Name | Available for ad prefetch | SCTE-35 specification section | Description | 
| --- | --- | --- | --- | 
| [avail.index] | Yes |  | A number that represents the position of an ad avail in an index. At the start of a playback session, MediaTailor creates an index of all the ad avails in a manifest and stores the index for the remainder of the session. When MediaTailor makes a request to the ADS to fill the avail, it includes the ad avail index number. This parameter enables the ADS to improve ad selection by using features like competitive exclusion and frequency capping. | 
| [avail.random] | Yes |  | A random number between 0 and 10,000,000,000, as a long number, that MediaTailor generates for each request to the ADS. Some ad servers use this parameter to enable features such as separating ads from competing companies. | 
| [scte.archive\$1allowed\$1flag] | Yes | 10.3.3.1 | An optional Boolean value. When this value is 0, recording restrictions are asserted on the segment. When this value is 1, recording restrictions are not asserted on the segment. | 
| [scte.avail\$1num] | Yes | 9.7.2.1 | The value parsed by MediaTailor from the SCTE-35 field avail\$1num, as a long number. MediaTailor can use this value to designate linear ad avail numbers.Value must be an integer. | 
| [scte.avails\$1expected] | Yes | 9,7.2.1 | An optional long value that gives the expected count of avails within the current event. | 
| [scte.delivery\$1not\$1restricted\$1flag] | Yes | 10.3.3.1 | An optional Boolean value. When this value is 0, the next five bits are reserved. When this value is 1, the next five bits take on the meanings as described in the SCTE-35 specification. | 
| [scte.device\$1restrictions] | Yes | 10.3.3.1 | An optional integer value that signals three pre-defined, independent, and non-hierarchical groups of devices. For more information about this variable, see the segments\$1expected description in the SCTE-35 specification. | 
| [scte.event\$1id] | Yes | 9.1 and 9.7.2.1 | The value parsed by MediaTailor from the SCTE-35 field splice\$1event\$1id, as a long number. MediaTailor uses this value to designate linear ad avail numbers or to populate ad server query strings, like ad pod positions.Value must be an integer. | 
| [scte.no\$1regional\$1blackout\$1flag] | Yes | 10.3.3.1 | An optional Boolean value. When this value is 0, regional blackout restrictions apply to the segment. When this value is 1, regional blackout restrictions do not apply to the segment. | 
| [scte.segment\$1num] | Yes | 10.3.3.1 | An optional integer value that numbers segments within a collection of segments. For more information about this variable, see the segment\$1num description in the SCTE-35 specification. | 
| [scte.segmentation\$1event\$1id]  | Yes | 10.3.3.1 | MediaTailor exposes this variable as [scte.event_id](#scte.event_id). | 
| [scte.segmentation\$1type\$1id] | Yes | 10.3.3.1 | An optional 8-bit integer value that specifies the segmentation type. For more information about this variable, see the segmentation\$1type\$1id description in the SCTE-35 specification. | 
| [scte.segmentation\$1upid] |  `segmentation_upid_type`: Yes `private_data`: Yes  |  **segmentation\$1upid**: 10.3.3.1 Managed Private UPID: 10.3.3.3  |  Corresponds to the SCTE-35 `segmentation_upid` element. The `segmentation_upid` element contains `segmentation_upid_type` and `segmentation_upid_length`. MediaTailor supports the following `segmentation_upid` types: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/variables-session.html)  | 
| [scte.segmentation\$1upid.assetId] | Yes |  | Used in conjunction with the Managed Private UPID (0xC) segmentation\$1 upid\$1type for podbuster workflows. MediaTailor derives this value from the assetId parameter in the MPU's private\$1data JSON structure. For more information, see [Managed Private UPID JSON structure for a podbuster workflow](#podbuster-workflow). | 
| [scte.segmentation\$1upid.cueData.key] | Yes |  | Used in conjunction with the Managed Private UPID (0xC) segmentation\$1 upid\$1type for podbuster workflows. MediaTailor derives this value from the cueData.key parameter in the MPU's private\$1data JSON structure. For more information, see [Managed Private UPID JSON structure for a podbuster workflow](#podbuster-workflow). | 
| [scte.segmentation\$1upid.cueData.value] | Yes |  | Used in conjunction with the Managed Private UPID (0xC) segmentation\$1 upid\$1type for podbuster workflows. MediaTailor derives this value from the cueData.key parameter in the MPU's private\$1data JSON structure. For more information, see [Managed Private UPID JSON structure for a podbuster workflow](#podbuster-workflow).Value can be a string. | 
| [scte.segmentation\$1upid.private\$1data.\$1index\$1] | Yes |  | Used in conjunction with the Managed Private UPID (0xC) segmentation\$1upid\$1type for targeted advertising workflows. MediaTailor splits colon-delimited segmentation UPID tokens and creates indexed session variables. The index corresponds to the position in the colon-delimited list, ignoring leading whitespace from the initial colon. For example, if `segmentation_upid = ":3213214:2313321/5:3943"`, then: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/variables-session.html) Value can be a string. | 
| [scte.segments\$1expected] | Yes | 10.3.3.1 | An optional integer value that gives the expected count of individual segments within a collection of segments. For more information about this variable, see the segments\$1expected description in the SCTE-35 specification. | 
| [scte.sub\$1segment\$1num] | Yes | 10.3.3.1 | An optional integer value that identifies a particular sub-segment within a collection of sub-segments. For more information about this variable, see the sub\$1segment\$1num description in the SCTE-35 specification. | 
| [scte.sub\$1segments\$1expected] | Yes | 10.3.3.1 | An optional integer value that gives the expected count of individual sub-segments within a collection of sub-segments. For more information about this variable, see the sub\$1segments\$1expected description in the SCTE-35 specification. | 
| [scte.unique\$1program\$1id] | Yes | 9.7.2.1 | The integer value parsed by MediaTailor from the SCTE-35 splice\$1insert field unique\$1program\$1id. The ADS uses the unique program ID (UPID) to provide program-level ad targeting for live linear streams. If the SCTE-35 command is not splice insert, MediaTailor sets this to an empty value.Value must be an integer. | 
| [session.avail\$1duration\$1ms] | Yes |  |  The duration in milliseconds of the ad availability slot. The default value is 300,000 ms. AWS Elemental MediaTailor obtains the duration value from the input manifest as follows: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/variables-session.html)  | 
| [session.avail\$1duration\$1secs] | Yes |  | The duration in seconds of the ad availability slot, or ad avail, rounded to the nearest second. MediaTailor determines this value the same way it determines [session.avail\$1duration\$1ms]. | 
| [session.client\$1ip] | No |  | The remote IP address that the MediaTailor request came from. If the X-forwarded-for header is set, then that value is what MediaTailor uses for the client\$1ip. | 
| [session.id] | No |  | A unique numeric identifier for the current playback session. All requests that a player makes for a session have the same id, so it can be used for ADS fields that are intended to correlate requests for a single viewing. | 
| [session.referer] | No |  | Usually, the URL of the page that is hosting the video player. MediaTailor sets this variable to the value of the Referer header that the player used in its request to MediaTailor. If the player doesn't provide this header, MediaTailor leaves the [session.referer] empty. If you use a content delivery network (CDN) or proxy in front of the manifest endpoint and you want this variable to appear, proxy the correct header from the player here. | 
| [session.user\$1agent] | No |  | The User-Agent header that MediaTailor received from the player's session initialization request. If you're using a CDN or proxy in front of the manifest endpoint, you must proxy the correct header from the player here. | 
| [session.uuid] | No |  |  Alternative to **[session.id]**. This is a unique identifier for the current playback session, such as the following: <pre>e039fd39-09f0-46b2-aca9-9871cc116cde</pre>  | 
| [avail.source\$1content\$1time\$1epoch\$1ms] | No |  |  For HLS the value is the PDT of the origin segment that started the avail. For DASH the value is the `<SupplementalProperty> urn:scte:dash:utc-time` of the `<Period>` that contains the `<EventStream>`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/variables-session.html)  | 

**Example**  
If the ADS requires a query parameter named `deviceSession` to be passed with the unique session identifier, the template ADS URL in AWS Elemental MediaTailor could look like the following:  

```
https://my.ads.server.com/path?deviceSession=[session.id]
```
AWS Elemental MediaTailor automatically generates a unique identifier for each stream, and enters the identifier in place of `session.id`. If the identifier is `1234567`, the final request that MediaTailor makes to the ADS would look something like this:  

```
https://my.ads.server.com/path?deviceSession=1234567
```
If the ADS requires several query parameters to be passed, the template ADS URL in AWS Elemental MediaTailor could look like the following:  

```
https://my.ads.server.com/sample?e=[scte.avails_expected]&f=[scte.segment_num]&g=[scte.segments_expected]&h=[scte.sub_segment_num]&j=[scte.sub_segments_expected]&k=[scte.segmentation_type_id]
```
The following DASH marker example XML fragment shows how to use `scte35:SpliceInsert`:  

```
<Period start="PT444806.040S" id="123456" duration="PT15.000S">
  <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2013:xml">
    <Event duration="1350000">
      <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="180832" tier="4095">
        <scte35:SpliceInsert spliceEventId="1234567890" spliceEventCancelIndicator="false" outOfNetworkIndicator="true" spliceImmediateFlag="false" uniqueProgramId="1" availNum="1" availsExpected="1">
          <scte35:Program><scte35:SpliceTime ptsTime="5672624400"/></scte35:Program>
          <scte35:BreakDuration autoReturn="true" duration="1350000"/>
        </scte35:SpliceInsert>
      </scte35:SpliceInfoSection>
```
The following DASH marker example XML fragment shows how to use `scte35:TimeSignal`:  

```
<Period start="PT346530.250S" id="123456" duration="PT61.561S">
  <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2013:xml">
    <Event duration="5310000">
      <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="183003" tier="4095">
        <scte35:TimeSignal>
          <scte35:SpliceTime ptsTime="3442857000"/>
        </scte35:TimeSignal>
        <scte35:SegmentationDescriptor segmentationEventId="1234567" segmentationEventCancelIndicator="false" segmentationDuration="8100000" segmentationTypeId="52" segmentNum="0" segmentsExpected="0">
          <scte35:DeliveryRestrictions webDeliveryAllowedFlag="false" noRegionalBlackoutFlag="false" archiveAllowedFlag="false" deviceRestrictions="3"/>
          <scte35:SegmentationUpid segmentationUpidType="12" segmentationUpidLength="2">0100</scte35:SegmentationUpid>
        </scte35:SegmentationDescriptor>
      </scte35:SpliceInfoSection>
    </Event>
```
The following DASH marker example XML fragment shows how to use `scte35:Binary`:  

```
<Period start="PT444806.040S" id="123456" duration="PT15.000S">
  <EventStream schemeIdUri="urn:scte:scte35:2014:xml+bin" timescale="1">
    <Event presentationTime="1541436240" duration="24" id="29">
      <scte35:Signal xmlns="http://www.scte.org/schemas/35/2016">
        <scte35:Binary>/DAhAAAAAAAAAP/wEAUAAAHAf+9/fgAg9YDAAAAAAAA25aoh</Binary>
      </scte35:Signal>
    </Event>
    <Event presentationTime="1541436360" duration="24" id="30">
      <scte35:Signal xmlns="http://www.scte.org/schemas/35/2016">
        <scte35:Binary>QW5vdGhlciB0ZXN0IHN0cmluZyBmb3IgZW5jb2RpbmcgdG8gQmFzZTY0IGVuY29kZWQgYmluYXJ5Lg==</Binary>
      </scte35:Signal>
    </Event>
```
The following HLS tag example shows how to use `EXT-X-DATERANGE`:  

```
#EXT-X-DATERANGE:ID="splice-6FFFFFF0",START-DATE="2014-03-05T11:
15:00Z",PLANNED-DURATION=59.993,SCTE35-OUT=0xFC002F0000000000FF0
00014056FFFFFF000E011622DCAFF000052636200000000000A0008029896F50
000008700000000
```
The following HLS tag example shows how to use `EXT-X-CUE-OUT`:  

```
#EXT-OATCLS-SCTE35:/DA0AAAAAAAAAAAABQb+ADAQ6QAeAhxDVUVJQAAAO3/PAAEUrEoICAAAAAAg+2UBNAAANvrtoQ==  
#EXT-X-ASSET:CAID=0x0000000020FB6501  
#EXT-X-CUE-OUT:201.467
```
The following HLS tag example shows how to use `EXT-X-SPLICEPOINT-SCTE35`:  

```
#EXT-X-SPLICEPOINT-SCTE35:/DA9AAAAAAAAAP/wBQb+uYbZqwAnAiVDVUVJAAAKqX//AAEjW4AMEU1EU05CMDAxMTMyMjE5M19ONAAAmXz5JA==
```
The following example shows how to use `scte35:Binary` decode:  

```
{
  "table_id": 252,
  "section_syntax_indicator": false,
  "private_indicator": false,
  "section_length": 33,
  "protocol_version": 0,
  "encrypted_packet": false,
  "encryption_algorithm": 0,
  "pts_adjustment": 0,
  "cw_index": 0,
  "tier": "0xFFF",
  "splice_command_length": 16,
  "splice_command_type": 5,
  "splice_command": {
    "splice_event_id": 448,
    "splice_event_cancel_indicator": false,
    "out_of_network_indicator": true,
    "program_splice_flag": true,
    "duration_flag": true,
    "splice_immediate_flag": false,
    "utc_splice_time": {
      "time_specified_flag": false,
      "pts_time": null
    },
    "component_count": 0,
    "components": null,
    "break_duration": {
      "auto_return": false,
      "duration": {
        "pts_time": 2160000,
        "wall_clock_seconds": 24.0,
        "wall_clock_time": "00:00:24:00000"
      }
    },
    "unique_program_id": 49152,
    "avail_num": 0,
    "avails_expected": 0
    "segment_num": 0,
    "segments_expected": 0,
    "sub_segment_num": 0,
    "sub_segments_expected": 0
  },
  "splice_descriptor_loop_length": 0,
  "splice_descriptors": null,
  "Scte35Exception": {
    "parse_status": "SCTE-35 cue parsing completed with 0 errors.",
    "error_messages": [],
    "table_id": 252,
    "splice_command_type": 5
  }
}
```

# MediaTailor player variables for ADS requests
<a name="variables-player"></a>

AWS Elemental MediaTailor sends data received from the player to the ADS when you configure AWS Elemental MediaTailor to specify `player_params.<query_parameter_name>` variables in the template ADS URL. For example, if the player sends a query parameter named `user_id` in its request to MediaTailor, to pass that data in the ADS request, include `[player_params.user_id]` in the ADS URL configuration. 

This allows you to control the query parameters that are included in the ADS request. Typically, you add a special query parameter that the ADS recognizes to the ADS request URL and provide key-value pairs as the value of the parameter. 

The examples used in the following procedure use the following key-value pairs:
+ *param1* with a value of *value1:*
+ *param2* with a value of *value2:*

**To add query parameters as key-value pairs** 

1. In AWS Elemental MediaTailor, configure the ADS request template URL to reference the parameters. The following URL shows the inclusion of the example parameters: 

   ```
   https://my.ads.com/path?param1=[player_params.param1]&param2=[player_params.param2]
   ```

1. (Optional) For server-side ad-tracking reporting, URL-encode the key-value pairs on the player. When MediaTailor receives the session initialization request, it URL-decodes the values once before substituting them into the ADS request URL. 
**Note**  
If your ADS requires a URL-encoded value, URL-encode the value twice on the player. This way, the decoding done by MediaTailor results in a once-encoded value for the ADS. 

   For example, if the decoded representation of the values sent to the ADS is `param1=value1:&param2=value2:`, then the URL-encoded representation is `param1=value1%3A&param2=value2%3A`.

1. In the session initialization call from the player, pass the key-value pairs to MediaTailor as the value of a single query parameter. The following example calls provide the example key-value pairs for server- and client-side ad tracking reporting.
   + Example requests for server-side ad-tracking reporting - using URL-encoded pairs

     HLS:

     ```
     <master>.m3u8?ads.param1=value1%3A&ads.param2=value2%3A
     ```

     DASH:

     ```
     <manifest>.mpd?ads.param1=value1%3A&ads.param2=value2%3A
     ```
   + Example request for client-side ad-tracking reporting - with no URL-encoding

     HLS:

     ```
     POST <master>.m3u8
         {
             "adsParams": {
                "param1": "value1:",
                "param2": "value2:"
            }
         }
     ```

     DASH:

     ```
     POST <manifest>.mpd
         {
             "adsParams": {
                "param1": "value1:",
                "param2": "value2:"
            }
         }
     ```

For server-side reporting, MediaTailor decodes the parameters when the player request is received. For client-side reporting, it doesn't alter the parameters received in the JSON payload. MediaTailor sends the following request to the ADS:

```
https://my.ads.com/<path>?param1=value1:&param2=value2:
```

In this way, the `param1` and `param2` key-value pairs are included as first-class query parameters in the ADS request.

# MediaTailor domain variables for multiple content sources
<a name="variables-domains"></a>

AWS Elemental MediaTailor dynamic domain variables allow you to 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. For setup procedures, see [Creating and using configuration aliases with MediaTailor](creating-configuration-aliases.md). For detailed reference information, see [MediaTailor configuration aliases overview](configuration-aliases-overview.md). 

# 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]
  ```

# MediaTailor passing parameters to ADS
<a name="passing-paramters-to-the-ads"></a>

AWS Elemental MediaTailor supports setting up dynamic variables in MediaTailor requests to the ADS using the following steps. 
+ For information about supported formatting for query parameters, see [MediaTailor parameter reference and limitations](parameter-comprehensive-reference.md).
+ For configuration aliases and domain variables, see [MediaTailor configuration aliases overview](configuration-aliases-overview.md).
+ For additional customizations to the ADS request, see [Advanced usage](#variables-advanced-usage).

**Session initialization methods**  
MediaTailor supports multiple methods for session initialization and parameter passing: 

1. **POST with Request Body:**

   ```
   POST <master>.m3u8
   {
       "adsParams": {"param1": "value1", "param2": "value2"},
       "playerParams": {"param3": "value3"}
   }
   ```

1. **Query Parameters in URL:**

   ```
   GET <master>.m3u8?ads.param1=value1&ads.param2=value2&playerParams.param3=value3
   ```

**Important**  
You can only specify parameters once, at initialization time. Configuration aliases resolve to actual values before forwarding. 

**To pass session and player information to the ADS**

1. Work with the ADS to determine the information that it needs to respond to an ad query from AWS Elemental MediaTailor. 

1. Create a configuration in MediaTailor that uses a template ADS request URL that satisfies the ADS requirements. In the URL, include static parameters and include placeholders for dynamic parameters. Enter your template URL in the configuration's **Ad decision server** field. 

   In the following example template URL, `correlation` provides session data, and `deviceType` provides player data: 

   ```
   https://my.ads.server.com/path?correlation=[session.id]&deviceType=[player_params.deviceType]
   ```

1. On the player, configure the session initiation request for AWS Elemental MediaTailor to provide parameters for the player data. Include your parameters in the session initiation request, and omit them from subsequent requests for the session. 

   The type of call that the player makes to initialize the session determines whether the player (client) or MediaTailor (server) provides ad-tracking reporting for the session. For information about these two options, see [Reporting ad tracking data](ad-reporting.md). 

   Make one of the following types of calls, depending on whether you want server- or client-side ad-tracking reporting. In both of the example calls, `userID` is intended for the ADS and `auth_token` is intended for the origin:
   + (Option) Call for server-side ad-tracking reporting – Prefix the parameters that you want MediaTailor to send to the ADS with `ads`. Leave the prefix off for parameters that you want MediaTailor to send to the origin server: 

     The following examples show incoming requests for HLS and DASH to AWS Elemental MediaTailor. MediaTailor uses the `deviceType` in its request to the ADS and the `auth_token` in its request to the origin server. 

     HLS example:

     ```
     GET master.m3u8?ads.deviceType=ipad&auth_token=kjhdsaf7gh
     ```

     DASH example:

     ```
     GET manifest.mpd?ads.deviceType=ipad&auth_token=kjhdsaf7gh
     ```
   + (Option) Call for client-side ad-tracking reporting – Provide parameters for the ADS inside an `adsParams` object.

     HLS example:

     ```
     POST master.m3u8
         {
             "adsParams": {
                "deviceType": "ipad"
            }
         }
     ```

     DASH example:

     ```
     POST manifest.mpd
         {
             "adsParams": {
                "deviceType": "ipad"
            }
         }
     ```

When the player initiates a session, AWS Elemental MediaTailor replaces the variables in the template ADS request URL with the session data and the player's `ads` parameters. It passes the remaining parameters from the player to the origin server. 

**Example MediaTailor requests with ad variables**  
The following examples show the calls to the ADS and origin server from AWS Elemental MediaTailor that correspond to the preceding player's session initialization call examples:   
+ MediaTailor calls the ADS with session data and the player's device type: 

  ```
  https://my.ads.server.com/path?correlation=896976764&deviceType=ipad
  ```
+ MediaTailor calls the origin server with the player's authorization token.
  + HLS example:

    ```
    https://my.origin.server.com/master.m3u8?auth_token=kjhdsaf7gh
    ```
  + DASH example:

    ```
    https://my.origin.server.com/manifest.mpd?auth_token=kjhdsaf7gh
    ```

## Advanced usage
<a name="variables-advanced-usage"></a>

You can customize the ADS request in many ways with player and session data. You only need to include the ADS host name. 

The following examples show some of the ways that you can customize your request: 
+ Concatenate player parameters and session parameters to create new parameters. Example: 

  ```
  https://my.ads.com?key1=[player_params.value1][session.id]
  ```
+ Use a player parameter as part of a path element. Example:

  ```
  https://my.ads.com/[player_params.path]?key=value
  ```
+ Use player parameters to pass both path elements and the keys themselves, rather than just values. Example: 

  ```
  https://my.ads.com/[player_params.path]?[player_params.key1]=[player_params.value1]
  ```

# MediaTailor parameter routing for ADS and origins
<a name="parameter-routing-behavior"></a>

AWS Elemental MediaTailor routes query parameters to different destinations based on their prefix and purpose. Understanding parameter routing is essential for implementing origin-specific functionality like time-shifted viewing with MediaPackage.

**Parameter routing rules**  
MediaTailor uses the following routing rules for query parameters:
+ **Origin parameters (no prefix):** Parameters without a specific prefix are passed through to the origin server for origin-specific functionality
+ **ADS parameters (`ads.` prefix):** Parameters prefixed with `ads.` are sent to the Ad Decision Server
+ **Manifest parameters (`manifest.` prefix):** Parameters prefixed with `manifest.` are used for CDN routing and authorization

**Example Parameter routing example**  
The following session initialization demonstrates parameter routing:  

```
POST /v1/session/123456789/originId/index.m3u8
{
    "adsParams": {
        "param1": "value1",
        "param2": "value2"
    },
    "manifestParams": {
        "auth_token": "abc123"
    }
}
```
In this example:  
+ `param1` and `param2` are sent to the ADS
+ `auth_token` is used for CDN routing and authorization
+ Parameters without prefixes would be passed to the origin server

## Origin server parameter behavior
<a name="origin-parameter-behavior"></a>

Parameters passed to origin servers enable origin-specific functionality such as time-shifted viewing, content filtering, and authentication.

**Common origin parameter use cases**  
Origin parameters are commonly used for:
+ **Time-shifted viewing:** `start` and `end` parameters for MediaPackage time-shifted content
+ **Content authentication:** Authentication tokens required by the origin server
+ **Content filtering:** Parameters that control which content variants are returned
+ **Origin-specific features:** Any parameters that the origin server uses for content processing

**Important**  
Parameters are processed at session initialization and maintained throughout the session. To modify parameters like time-shift windows, you must create a new session with updated values.

# MediaTailor and MediaPackage time-shifted viewing integration
<a name="mediapackage-integration-param"></a>

AWS Elemental MediaTailor can pass time-shifted viewing parameters to MediaPackage origins to enable startover and catch-up viewing functionality. This integration allows viewers to start watching live content from earlier points in time.

**MediaPackage time-shifted viewing parameters**  
MediaPackage supports the following time-shifted viewing parameters that can be passed through MediaTailor:
+ `start`: Epoch or ISO 8601 timestamp defining the beginning of the time-shifted manifest
+ `end`: Epoch or ISO 8601 timestamp defining the end of the time-shifted manifest
+ `time_delay`: Delay content availability by specified seconds
+ `manifest_window_seconds`: Request a manifest shorter than the configured window

**Example MediaTailor session initialization with MediaPackage time-shifted parameters**  
The following example shows how to initialize a session with time-shifted viewing parameters:  

```
GET /v1/master/123456789/originId/index.m3u8?start=2024-08-26T10:00:00Z&end=2024-08-26T11:00:00Z
```
Or using explicit session initialization:  

```
POST /v1/session/123456789/originId/index.m3u8
{
    "adsParams": {
        "param1": "value1"
    }
}
```
With additional query parameters:  

```
?start=2024-08-26T10:00:00Z&end=2024-08-26T11:00:00Z
```

**Parameter behavior during sessions**  
Time-shifted viewing parameters have specific behavior characteristics:
+ **Session initialization:** Parameters are processed when the session is created
+ **Parameter persistence:** Parameters remain associated with the session throughout playback
+ **Immutable after initialization:** Parameters cannot be changed during an active session
+ **New session required:** To modify time-shift windows, create a new session with updated parameter values

**MediaPackage startover window requirements**  
For time-shifted viewing to work with MediaPackage, ensure the following:

1. Configure a startover window on your MediaPackage endpoint (up to 24 hours)

1. Ensure your CDN forwards the necessary query parameters to MediaPackage

1. Use consistent playback windows across player sessions for better CDN caching

1. Verify that start and end times fall within the configured startover window

**Important**  
When using time-shifted viewing, use consistent playback windows across player sessions rather than generating unique start or end times for each viewer. This yields better caching at the CDN and avoids potential throttling.

For complete information about MediaPackage time-shifted viewing configuration and parameters, see [Time-shifted viewing with AWS Elemental MediaPackage](https://docs.aws.amazon.com/mediapackage/latest/ug/time-shifted.html) in the *AWS Elemental MediaPackage User Guide*.

# MediaTailor parameter session behavior and persistence
<a name="parameter-session-behavior"></a>

AWS Elemental MediaTailor processes parameters at session initialization and maintains them throughout the session lifecycle. Understanding session behavior is crucial for implementing dynamic parameter scenarios.

**Session initialization methods**  
MediaTailor supports multiple methods for session initialization with parameters:

1. **Implicit session initialization:** Parameters included in the initial manifest request

   ```
   GET /v1/master/123456789/originId/index.m3u8?manifest.auth_token=abc123&start=2024-08-26T10:00:00Z
   ```

1. **Explicit session initialization (POST):** Parameters provided in the request body

   ```
   POST /v1/session/123456789/originId/index.m3u8
   {
       "adsParams": {"param1": "value1"},
       "manifestParams": {"auth_token": "abc123"}
   }
   ```

1. **Explicit session initialization (GET):** Parameters provided as query parameters

   ```
   GET /v1/session/123456789/originId/index.m3u8?ads.param1=value1&manifestParams.auth_token=abc123
   ```

**Parameter persistence and immutability**  
MediaTailor parameter behavior follows these rules:
+ **One-time specification:** Parameters can only be specified once, at session initialization
+ **Session-wide persistence:** Parameters are maintained throughout the entire session
+ **Immutable after initialization:** Parameters cannot be modified after the session is created
+ **Configuration alias resolution:** Aliases are resolved to actual values before forwarding to destinations

**Parameter modification scenarios**  
To modify parameters during playback:
+ **Create new session:** Initialize a new session with updated parameter values
+ **Player transition:** Seamlessly transition the player to the new session
+ **Parameter inheritance:** Carry forward unchanged parameters to maintain consistency

**Example Modifying time-shift parameters**  
To change from a 1-hour window to a 2-hour window:  

1. Current session: `start=2024-08-26T10:00:00Z&end=2024-08-26T11:00:00Z`

1. Create new session: `start=2024-08-26T10:00:00Z&end=2024-08-26T12:00:00Z`

1. Transition player to new session URL

**Important**  
Multiple multivariant playlist requests for a single session do not update parameters after the first request. Parameters remain immutable for the session duration.

# MediaTailor parameter reference and limitations
<a name="parameter-comprehensive-reference"></a>

Before configuring dynamic ad variables, understand the parameter formatting requirements and limitations that apply to all MediaTailor configurations.

AWS Elemental MediaTailor provides comprehensive information about parameter character restrictions, length limitations, and supported formats for both manifest query parameters and ADS parameters. 

## Manifest query parameter character restrictions
<a name="manifest-parameter-character-restrictions"></a>

Manifest query parameters support specific characters and have defined length limitations. 

**Supported characters (without URL-encoding)**  
You can use the following characters directly in manifest query parameters: 
+ Alphanumeric characters (A-Z, a-z, 0-9)
+ Periods (.)
+ Hyphens (-)
+ Underscores (\$1)
+ Backslashes (\$1)

**Supported characters with URL-encoding**  
The following special characters are supported when URL-encoded: 
+ 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. 

**Unsupported characters**  
You cannot use the following characters in manifest query parameters without URL-encoding: `:`, `?`, `&`, `=`, `%`, `/` (forward slash). 

**Important**  
MediaTailor doesn't support double characters such as %%% or ==. You can't use full URLs as manifest query parameter values due to character restrictions. 

**Length limitations**  
The total length of all manifest query parameters (keys and values combined) must not exceed 2000 characters. 

## ADS parameter length limitations
<a name="ads-parameter-limitations"></a>

The following length limitations apply to parameters used in requests to the ADS: 
+ **ADS parameter name**: Maximum 10,000 characters
+ **ADS parameter value**: Maximum 25,000 characters
+ **ADS URL**: Maximum 25,000 characters

# MediaTailor parameter troubleshooting guide
<a name="parameter-troubleshooting"></a>

AWS Elemental MediaTailor provides guidance for troubleshooting common parameter-related issues in MediaTailor, including character restrictions, URL encoding problems, and configuration alias errors. 

## Character restriction errors
<a name="parameter-character-restriction-errors"></a>

Parameter values that contain unsupported characters may cause errors or unexpected behavior. 

**Common symptoms**  
The following symptoms may indicate character restriction issues: 
+ Parameters not appearing in manifest URLs
+ HTTP 400 errors during session initialization
+ Truncated or corrupted parameter values
+ ADS requests failing due to malformed URLs

**Resolution steps**  
To resolve character restriction errors: 

1. Review parameter values for unsupported characters: `:`, `?`, `&`, `=`, `%`, `/`

1. Apply proper URL-encoding for special characters (see [MediaTailor parameter reference and limitations](parameter-comprehensive-reference.md))

1. Avoid double characters such as `%%%` or `==`

1. Consider alternative parameter formats if full URLs cannot be used

**Example URL encoding example**  
Instead of using:   

```
manifest.redirect_url=https://example.com/path?param=value
```
Use URL-encoded format:   

```
manifest.redirect_url=https%3A%2F%2Fexample.com%2Fpath%3Fparam%3Dvalue
```

## Length limitation errors
<a name="parameter-length-limitation-errors"></a>

Parameters that exceed length limits may be truncated or cause errors. 

**Length limits**  
The following length limits apply (see [MediaTailor parameter reference and limitations](parameter-comprehensive-reference.md) for complete details):
+ Manifest query parameters (total): 2000 characters
+ ADS parameter names: 10,000 characters
+ ADS parameter values: 25,000 characters
+ ADS URLs: 25,000 characters

**Resolution strategies**  
To handle length limitations: 

1. Use shorter parameter names and values where possible

1. Split large parameter values into multiple smaller parameters

1. Use configuration aliases to map short aliases to longer values (see [MediaTailor configuration aliases overview](configuration-aliases-overview.md))

1. Consider using external storage for large data with parameter references

## Configuration alias errors
<a name="parameter-configuration-alias-errors"></a>

Configuration alias issues can result in HTTP 400 errors or unexpected parameter values. 

**Common configuration alias errors**  
The following errors commonly occur with configuration aliases: 
+ HTTP 400 error: Missing or invalid alias value
+ Domain variables not resolving correctly
+ Player parameters not being replaced with alias values

**Resolution checklist**  
To resolve configuration alias errors: 

1. Verify all domain variables are defined as `ConfigurationAliases`

1. Ensure player parameter variables use `player_params.` prefix

1. Confirm the list of aliased values is exhaustive for domain variables in critical URLs (`VideoContentSourceUrl`, `AdSegmentUrlPrefix`, `ContentSegmentUrlPrefix`)

1. Check that session initialization requests specify valid alias values

1. Validate JSON structure of ConfigurationAliases parameter

For detailed troubleshooting guidance, see [MediaTailor configuration aliases troubleshooting guide](configuration-aliases-troubleshooting.md).

**Example Configuration alias validation**  
Ensure your configuration includes all required aliases:   

```
"ConfigurationAliases": {
    "player_params.origin_domain": {
        "pdx": "abc.mediapackage.us-west-2.amazonaws.com",
        "iad": "xyz.mediapackage.us-east-1.amazonaws.com"
        // Must include all possible values used in session initialization
    }
}
```

## Parameter processing flow issues
<a name="parameter-processing-flow-issues"></a>

Understanding the parameter processing flow helps troubleshoot issues with parameter forwarding and transformation. 

**Parameter processing order**  
MediaTailor processes parameters in the following order: 

1. Session initialization parameter validation

1. Configuration alias resolution (if applicable)

1. Parameter filtering (ADS vs origin vs manifest)

1. URL encoding and formatting

1. Parameter application to URLs

**Debugging parameter flow**  
To debug parameter processing issues: 

1. Verify parameters are correctly specified in session initialization

1. Check that configuration aliases resolve to expected values

1. Confirm parameters appear in the correct URLs (manifest, ADS, origin)

1. Validate URL encoding is applied correctly

**Example Parameter flow example**  
Session initialization:   

```
POST master.m3u8
{
    "playerParams": {"origin_domain": "pdx"},
    "manifestParams": {"test": "123"}
}
```
After alias resolution and processing:   
+ Origin request: `https://abc.mediapackage.us-west-2.amazonaws.com/out/v1/abcd`
+ Manifest URL: `/v1/master/.../index.m3u8?aws.sessionId=session&test=123`

## Security considerations and best practices
<a name="parameter-security-considerations-troubleshooting"></a>

MediaTailor implements security measures for parameter handling to prevent common security issues. 

**Security measures**  
MediaTailor implements the following security measures: 

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

**Best practices**  
Follow these best practices for secure parameter handling: 
+ Validate parameter values on the client side before sending
+ Use configuration aliases to limit possible parameter values
+ Avoid including sensitive information in parameters
+ Monitor parameter usage for unusual patterns
+ Keep parameter values within recommended length limits

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

AWS Elemental MediaTailor provides systematic troubleshooting guidance for common configuration aliases issues and error scenarios. 

## Configuration alias validation errors
<a name="configuration-alias-validation-errors"></a>

When configuration aliases are missing or invalid, MediaTailor returns specific error responses to help identify the issue. 

**Common error scenarios**  
The following table describes common configuration alias errors and their resolution steps: 


| Error | Cause | Resolution | 
| --- | --- | --- | 
| HTTP 400: Invalid player parameter alias | Player parameter value not found in ConfigurationAliases | Verify that the player parameter value exists as a key in the corresponding ConfigurationAliases mapping | 
| HTTP 400: Missing required configuration alias | Domain variable used without corresponding ConfigurationAliases entry | Add the missing player parameter to ConfigurationAliases with all required alias mappings | 
| HTTP 400: Configuration validation failed | ConfigurationAliases structure is malformed or incomplete | Validate JSON structure and ensure all domain variables have corresponding aliases | 
| Empty string replacement in URLs | Non-domain variable alias not found | Add missing alias mapping or provide default value in ConfigurationAliases | 

**Validation checklist**  
Use the following checklist to validate your configuration aliases setup: 

1. **Domain variable coverage:** Ensure all variables used in domain portions of URLs have corresponding ConfigurationAliases entries

1. **Alias completeness:** Verify that all possible player parameter values are included as keys in the alias mappings

1. **JSON structure:** Validate that the ConfigurationAliases JSON is properly formatted and nested

1. **Parameter naming:** Confirm that all player parameters use the `player_params.` prefix

1. **Value consistency:** Ensure alias values are valid for their intended use (URLs, profile names, etc.)

## Debugging configuration alias resolution
<a name="configuration-alias-debugging"></a>

Follow this systematic approach to debug configuration alias resolution issues. 

**Step-by-step debugging methodology**  
Use the following steps to identify and resolve configuration alias issues: 

**Configuration alias debugging procedure**

1. **Verify configuration structure:** Confirm that your playback configuration includes properly formatted ConfigurationAliases

   ```
   {
       "ConfigurationAliases": {
           "player_params.example_param": {
               "alias1": "value1",
               "alias2": "value2"
           }
       }
   }
   ```

1. **Check player parameter format:** Ensure session initialization includes correctly formatted player parameters

   ```
   {
       "playerParams": {
           "example_param": "alias1"
       }
   }
   ```

1. **Validate alias mapping:** Confirm that the player parameter value ("alias1") exists as a key in the ConfigurationAliases mapping

1. **Test with simple configuration:** Start with a minimal configuration to isolate the issue

1. **Monitor error responses:** Check MediaTailor error responses for specific validation messages

1. **Verify resolved URLs:** Confirm that the final resolved URLs are valid and accessible

## Configuration aliases best practices
<a name="configuration-alias-best-practices"></a>

Follow these best practices to ensure reliable configuration alias implementation. 

**Security considerations**  
Implement the following security measures when you use configuration aliases: 
+ **Input validation:** Validate all player parameter values before using them in alias resolution
+ **Alias value sanitization:** Ensure alias values contain only expected characters and formats
+ **Domain restrictions:** Limit domain aliases to trusted, controlled domains
+ **Access control:** Restrict configuration modification to authorized personnel only

**Performance optimization**  
Optimize configuration alias performance with these recommendations: 
+ **Minimize alias count:** Use only necessary aliases to reduce processing overhead
+ **Efficient naming:** Use clear, consistent naming conventions for aliases and parameters
+ **Default values:** Provide sensible default aliases for common use cases
+ **Configuration caching:** Leverage MediaTailor's configuration caching for improved performance

**Maintenance and monitoring**  
Maintain reliable configuration alias operations with these practices: 
+ **Regular validation:** Periodically validate that all alias mappings are current and functional
+ **Error monitoring:** Monitor for HTTP 400 errors related to missing or invalid aliases
+ **Documentation:** Maintain clear documentation of all alias mappings and their purposes
+ **Testing procedures:** Implement comprehensive testing for all alias combinations

# 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
   ```

# Reporting ad tracking data
<a name="ad-reporting"></a>

MediaTailor provides two options for tracking and reporting on how much of an ad a viewer has watched. In the server-side ad reporting approach, MediaTailor tracks the ad and sends beacons (tracking signals) directly to the ad server. Alternatively, in the client-side tracking approach, the client player (the user's device) tracks the ad and sends the beacons to the ad server. The type of ad reporting used in a playback session depends on the specific request the player makes to initiate the session in MediaTailor.

For information about passing session and player data to the ad server using dynamic variables, see [MediaTailor dynamic ad variables for ADS requests](variables.md). For details about session initialization parameters, see [MediaTailor manifest query parameters](manifest-query-parameters.md).

**Topics**
+ [MediaTailor server-side ad tracking and reporting](ad-reporting-server-side.md)
+ [Client-side ad tracking](ad-reporting-client-side.md)

# MediaTailor server-side ad tracking and reporting
<a name="ad-reporting-server-side"></a>

AWS Elemental MediaTailor defaults to server-side reporting for comprehensive ad tracking and measurement. With server-side reporting, when the player requests an ad URL from the manifest, the service reports ad consumption directly to the ad tracking URL. After the player initializes a playback session with MediaTailor, no further input is required from you or the player to perform server-side reporting. As each ad is played back, MediaTailor sends beacons to the ad server to report how much of the ad has been viewed. MediaTailor sends beacons for the start of the ad and for the ad progression in quartiles: the first quartile, midpoint, third quartile, and ad completion.

**To perform server-side ad reporting**
+ From the player, initialize a new MediaTailor playback session using a request in one of the following formats, according to your protocol:
  + Example: HLS format

    ```
    GET <mediatailorURL>/v1/master/<hashed-account-id>/<origin-id>/<asset-id>?ads.<key-value-pairs-for-ads>&<key-value-pairs-for-origin-server>
    ```
  + Example: DASH format

    ```
    GET <mediatailorURL>/v1/dash/<hashed-account-id>/<origin-id>/<asset-id>?ads.<key-value-pairs-for-ads>&<key-value-pairs-for-origin-server>
    ```

  The key-value pairs are the dynamic targeting parameters for ad tracking. For information about adding parameters to the request, see [MediaTailor dynamic ad variables for ADS requests](variables.md).

AWS Elemental MediaTailor responds to the request with the manifest URL. The manifest contains URLs for the media manifests. The media manifests contain embedded links for ad segment requests.

**Note**  
When MediaTailor encounters a double-slash (//) in a tracking URL, it collapses the slashes to one (/).

When the player requests playback from an ad segment URL (`/v1/segment` path), AWS Elemental MediaTailor sends the appropriate beacon to the ad server through the ad tracking URLs. At the same time, the service issues a redirect to the actual `*.ts` ad segment. The ad segment is either in the Amazon CloudFront distribution where MediaTailor stores transcoded ads, or in the content delivery network (CDN) where you have cached the ad. 

The following sections provide more information about working with server-side ad tracking from MediaTailor.

**Topics**
+ [SGAI server-side tracking](ad-reporting-server-side-sgai.md)
+ [Beacon glossary](ad-reporting-server-side-beacon-glossary.md)
+ [Timing and caching behavior](ad-reporting-server-side-timing-behavior.md)
+ [Tracking features](ad-reporting-server-side-features.md)

# Server-side tracking with server-guided ad insertion (SGAI)
<a name="ad-reporting-server-side-sgai"></a>

When you use server-guided ad insertion (SGAI), server-side tracking uses a *sessionless beaconing* mechanism that differs from the stitched-mode approach described above. Instead of MediaTailor stitching ad segments into the content manifest (where it tracks `/v1/segment` requests), SGAI returns ad references as separate playlists in an asset list response with beacon metadata embedded in the ad URIs.

## How sessionless server-side beaconing works
<a name="ad-reporting-server-side-sgai-how-it-works"></a>

The following steps describe how server-side beaconing works for SGAI sessions:

1. **Session initialization**: The player requests the HLS multivariant playlist with `aws.insertionMode=GUIDED`. Server-side reporting is the default (no `aws.reportingMode` parameter is needed). Unlike stitched mode, the session initialization response does *not* include a `trackingUrl`.

1. **Cacheable manifest**: MediaTailor returns a cacheable manifest containing `EXT-X-DATERANGE` tags with `CLASS="com.apple.hls.interstitial"` and `X-ASSET-LIST` attributes pointing to the MediaTailor interstitial asset list endpoint.

1. **Asset list with beacon metadata**: When the player encounters an ad break, it fetches the asset list. MediaTailor returns a JSON response where each ad URI includes encrypted beacon metadata:

   ```
   {
     "ASSETS": [
       {
         "DURATION": 30.0,
         "URI": "https://cdn.example.com/ad/master.m3u8?awsBeaconData=<encrypted>&awsBeaconDomain=<MediaTailor-endpoint>&awsConfigurationName=<config-name>"
       }
     ]
   }
   ```

   When server-side reporting is active, the response does *not* include a `TRACKING` section. The ad URIs carry all beacon data.

1. **HLS variable substitution**: The player fetches the ad multivariant playlist. The ad manifest uses `#EXT-X-DEFINE:QUERYPARAM` directives to pass the beacon parameters from the URI query string into segment URLs via HLS variable substitution:

   ```
   #EXTM3U
   #EXT-X-DEFINE:QUERYPARAM="awsBeaconData"
   #EXT-X-DEFINE:QUERYPARAM="awsBeaconDomain"
   #EXT-X-DEFINE:QUERYPARAM="awsConfigurationName"
   #EXTINF:5.0,
   {$awsBeaconDomain}/segment/hash/{$awsConfigurationName}/{$awsBeaconData}/0/0?aws.segmentRelativePath=asset_00001.ts
   ```

   The player resolves the `{$awsBeaconData}`, `{$awsBeaconDomain}`, and `{$awsConfigurationName}` variables using the values from the ad manifest URI query string, and then requests each ad segment through MediaTailor.

1. **Beacon firing on segment request**: As the player requests each ad segment, the request routes through MediaTailor. The service decrypts the beacon data, determines the segment's position within the ad (impression, first quartile, midpoint, third quartile, or complete), and fires the appropriate VAST tracking beacon to the ad server. MediaTailor then redirects the player to the actual ad content segment.

## Player requirements for SGAI server-side beaconing
<a name="ad-reporting-server-side-sgai-requirements"></a>

To use server-side beaconing with SGAI, your player must meet the following requirements:
+ HLS version 11 or later
+ Support for `EXT-X-DATERANGE` with `CLASS` attribute for HLS Interstitials
+ Support for `#EXT-X-DEFINE:QUERYPARAM` variable substitution (RFC 8216bis). The player must percent-decode the query parameter values before substituting them into segment URLs.

**Note**  
SGAI server-side beaconing is currently supported for HLS only. DASH is not yet supported for SGAI server-side beaconing.

## Comparison with stitched-mode server-side tracking
<a name="ad-reporting-server-side-sgai-comparison"></a>

The following table summarizes how server-side tracking differs between stitched and server-guided ad insertion:


| Aspect | Stitched (SSAI) | Server-guided (SGAI) | 
| --- | --- | --- | 
| Manifest cacheability | Per-session, not cacheable | Cacheable, shared across viewers | 
| Ad segment routing | Through /v1/segment/ using the session ID | Through /v1/segment/ using an encrypted beacon data blob | 
| Session state for beacons | Stored per session in MediaTailor | Sessionless — all state is carried in the encrypted awsBeaconData parameter | 
| Tracking URL at session init | Returned in the session initialization response | Not provided — beacon data is embedded in ad URIs in each asset list response | 
| DASH support | Supported | Not yet supported | 

**Note**  
For live SGAI sessions, you can enable manifest-based ad prefetching using `aws.guidedPrefetchMode=MANIFEST`. This is separate from the schedule-based prefetch API used with stitched (SSAI) sessions. For details, see [Guided prefetch with manifest heartbeating](sgai-guided-prefetch.md).

# Server-side tracking beacon glossary
<a name="ad-reporting-server-side-beacon-glossary"></a>

MediaTailor server-side tracking uses a standardized set of beacons to report ad viewing progress to ad servers and verification services. These beacons align with Interactive Advertising Bureau (IAB) standards for video ad measurement and provide accurate reporting of ad impressions and completion rates.


**Server-side tracking beacon types**  

| Beacon Type | When Fired | Purpose | Timing Details | 
| --- | --- | --- | --- | 
| Impression | When the player requests the first ad segment | Indicates that ad content has begun loading and is about to be displayed to the viewer | Fired on the first /v1/segment request for an ad. Aligns with IAB guidelines requiring ad content to begin loading before counting an impression. See [Server-side tracking workflow](ad-reporting-server-side-timing-behavior.md#ad-reporting-server-side-timing-behavior-workflow) for the complete sequence. | 
| Start | When the player begins rendering the ad content | Confirms that ad playback has actually started | Typically fired simultaneously with the impression beacon on the first segment request, but represents the actual start of ad rendering. This distinction is important for verification services that track both impression and start events separately. | 
| First Quartile | When the player reaches 25% of the ad duration | Measures continued ad viewing through the first quarter of the ad | Fired when the player requests the segment that contains the 25% point of the ad duration. For example, in a 20-second ad with 2-second segments, this would typically fire on the request for the 3rd segment (at approximately 4-6 seconds into the ad). | 
| Midpoint | When the player reaches 50% of the ad duration | Measures continued ad viewing through half of the ad | Fired when the player requests the segment that contains the 50% point of the ad duration. For example, in a 20-second ad with 2-second segments, this would typically fire on the request for the 5th segment (at approximately 8-10 seconds into the ad). | 
| Third Quartile | When the player reaches 75% of the ad duration | Measures continued ad viewing through three-quarters of the ad | Fired when the player requests the segment that contains the 75% point of the ad duration. For example, in a 20-second ad with 2-second segments, this would typically fire on the request for the 8th segment (at approximately 14-16 seconds into the ad). | 
| Complete | When the player reaches the end of the ad | Confirms that the entire ad was delivered to the viewer | Fired when the player requests the final segment of the ad. This indicates that the viewer has potentially seen the entire ad content. For example, in a 20-second ad with 2-second segments, this would typically fire on the request for the 10th segment (at approximately 18-20 seconds into the ad). | 

**Note**  
The exact timing of beacon firing depends on the segment duration and ad length. MediaTailor calculates the appropriate segment request that corresponds to each quartile position based on the specific ad duration and segment structure.

# Server-side tracking timing and caching behavior
<a name="ad-reporting-server-side-timing-behavior"></a>

In server-side reporting, MediaTailor fires tracking events based on actual segment requests from the player, not on manifest parsing or pre-loading activities. This approach ensures accurate impression counting that aligns with industry standards for video ad measurement.

## Key timing principles
<a name="ad-reporting-server-side-timing-behavior-principles"></a>

MediaTailor server-side tracking follows these fundamental timing principles:
+ **Tracking events fire on actual segment requests** - Beacons are sent only when the player makes HTTP requests to `/v1/segment` URLs, not during manifest parsing or caching.
+ **Player caching and pre-loading of manifests does NOT trigger events** - Players can parse, cache, or pre-load manifest information without generating any tracking events.
+ **Segment pre-fetching *will* trigger events** - If players pre-fetch actual ad segments before playback, this follows industry standard behavior where segment requests constitute valid impressions.
+ **Each /v1/segment request triggers appropriate beacon** - The specific tracking event (impression, quartile, completion) is determined by the ad position and segment being requested.
+ **Timing aligns with IAB standards** - The approach follows Interactive Advertising Bureau guidelines for video ad measurement and impression counting.

## Server-side tracking workflow
<a name="ad-reporting-server-side-timing-behavior-workflow"></a>

The following diagrams illustrate the complete server-side tracking workflow, showing when tracking events are fired in relation to player requests:

**Phase 1: Session initialization**  
The player requests a manifest from MediaTailor, which returns a personalized manifest containing ad segment URLs:  

![\[Session initialization phase showing player requesting manifest from MediaTailor and receiving personalized manifest with ad segment URLs.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/ss-track-phase1.png)


**Phase 2: Ad request and impression tracking**  
When the player requests the first ad segment, MediaTailor fires impression and start beacons to both the Ad Decision Server and Ad Verification Services:  

![\[Ad impression tracking phase showing MediaTailor sending both impression and start beacons to Ad Decision Server and Ad Verification Services when player requests first ad segment.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/ss-track-phase2.png)


**Phase 3: Quartile tracking**  
MediaTailor fires quartile beacons (first quartile, midpoint, third quartile, completion) based on subsequent segment requests:  

![\[Quartile tracking phase showing MediaTailor firing quartile beacons to both Ad Decision Server and Ad Verification Services as player requests subsequent ad segments.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/ss-track-phase3.png)


**Phase 4: Segment delivery**  
After firing tracking beacons, MediaTailor redirects to the actual ad segment from Amazon CloudFront or your CDN:  

![\[Segment delivery phase showing MediaTailor redirecting player to actual ad segment from CloudFront or CDN after firing tracking beacons.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/ss-track-phase4.png)


The server-side tracking workflow includes the following key timing behaviors:

1. **Session initialization** - The player requests a manifest from MediaTailor. MediaTailor returns a personalized manifest containing ad segment URLs with the `/v1/segment` path.

1. **Manifest parsing and caching** - The player parses the manifest and may pre-load or cache segment information. **No tracking events are fired during this phase**, regardless of player caching behavior.

1. **Ad segment request and impression tracking** - When the player actually requests the first ad segment (typically for playback), MediaTailor fires the impression beacon and start tracking event to both the Ad Decision Server and Ad Verification Services. This occurs on the actual HTTP request to the `/v1/segment` URL, not when the manifest is parsed.

1. **Quartile tracking based on segment requests** - MediaTailor fires quartile beacons (first quartile, midpoint, third quartile, completion) to both the Ad Decision Server and Ad Verification Services based on subsequent segment requests that correspond to the calculated quartile positions within the ad duration.

1. **Segment delivery** - After firing the appropriate tracking beacon, MediaTailor issues an HTTP redirect to the actual ad segment (either from Amazon CloudFront or your CDN).

## Player caching and pre-loading considerations
<a name="ad-reporting-server-side-timing-behavior-caching-considerations"></a>

MediaTailor server-side tracking is designed to be compatible with various player caching and pre-loading strategies while maintaining accurate impression measurement:
+ **Manifest pre-loading** - Players that pre-load or cache manifest information do not trigger tracking events. Tracking events are only fired when actual segment requests are made.
+ **Segment pre-fetching** - If a player pre-fetches ad segments before playback, tracking events will fire when those segments are requested, potentially earlier than the actual playback time. This behavior aligns with industry standards that consider segment requests as valid impressions.
+ **Player buffering** - Standard player buffering behavior (requesting segments slightly ahead of playback) will trigger tracking events at the appropriate times based on the segment request pattern.

## Troubleshooting tracking discrepancies
<a name="ad-reporting-server-side-timing-behavior-troubleshooting"></a>

If you notice discrepancies between MediaTailor server-side tracking and third-party metrics, consider the following factors:
+ **Player behavior differences** - Different players may have varying pre-fetching and buffering strategies that affect when segment requests are made.
+ **Network conditions** - Poor network conditions may cause players to request segments multiple times or at different intervals than expected.
+ **CDN configuration** - Incorrect CDN caching of `/v1/segment` requests can lead to missed or duplicate tracking events.
+ **Session management** - Ensure that each playback session uses a unique session identifier to prevent tracking event conflicts.

For detailed troubleshooting guidance, see [Troubleshooting common issues](monitoring-and-troubleshooting.md#troubleshooting-common-issues).

# MediaTailor server-side tracking features and capabilities
<a name="ad-reporting-server-side-features"></a>

AWS Elemental MediaTailor automatically applies these integrated server-side tracking features to optimize ad measurement accuracy and reliability. The system prevents duplicate beacons, manages traffic during high-volume periods, maintains proper event sequencing, and provides comprehensive performance monitoring without requiring any configuration from you. You only need to ensure your ad decision server (ADS) provides the tracking beacons in the VAST response.

**Note**  
These features are available for new customers starting September 30, 2025. Existing customers will have access throughout 2025 as part of ongoing service improvements. If you want immediate access to these features, contact [AWS Support](https://aws.amazon.com/premiumsupport/).

**Note**  
These features apply to both stitched (SSAI) and server-guided (SGAI) ad insertion methods. The beacon types and timing are the same in both modes. They differ in how MediaTailor triggers beacons — see [Server-side tracking with server-guided ad insertion (SGAI)](ad-reporting-server-side-sgai.md) for details on SGAI server-side beaconing.

## Beacon deduplication
<a name="ad-reporting-server-side-beacon-deduplication"></a>

MediaTailor prevents duplicate beacon firing for identical ad events. The server-side tracking system sends each impression, quartile, and completion beacon only once per ad viewing session. When video players request the same ad segment multiple times due to network conditions, bitrate changes, or buffering strategies, MediaTailor tracks fired beacons and blocks redundant transmissions.

Deduplication automatically resolves common scenarios that cause inflated beacon counts:
+ **Adaptive bitrate streaming** - When players download different quality variants of the same ad segment
+ **Network retry scenarios** - When players re-request segments due to network issues or timeouts
+ **Player buffering strategies** - When players pre-fetch or re-fetch segments for buffering purposes

The system is designed to fire impression beacons only once, even when players switch between different quality levels.

## Adaptive throttling and beacon retries
<a name="ad-reporting-server-side-adaptive-throttling"></a>

MediaTailor automatically manages beacon traffic rates based on server response indicators. The system monitors HTTP response patterns, connection timeouts, and error codes to detect congestion, then adjusts traffic rates accordingly. When the system identifies server stress indicators, it reduces traffic rates for the affected domain and automatically increases rates when servers demonstrate improved capacity.

The system monitors server health using these indicators:
+ **HTTP connection timeouts** - When measurement platforms don't respond within expected timeframes
+ **Error response codes** - 503, 504, and 507 responses that indicate server overload. Your ad server must also support these error codes for full compatibility.
+ **Response patterns** - Measurement platform performance changes that indicate capacity issues

Retry behavior automatically attempts delivery for up to 1 hour with minimum 30-second delays between attempts. This retry behavior cannot be configured. 

## Beacon traffic per second management
<a name="ad-reporting-server-side-tps-management"></a>

You can set TPS limits to control beacon delivery rates. This is the only configurable setting for server-side tracking features. Account-level limits cap the total number of ad tracking requests sent across all measurement partners. MediaTailor enforces a minimum TPS limit of 10,000 to provide sufficient capacity for enterprise-scale operations.

Submit an AWS support ticket to establish TPS limits with the following information:
+ **AWS account ID** - Your specific account identifier
+ **Target region** - The AWS region where you want the TPS limit applied
+ **Desired TPS threshold** - Your required transactions per second limit (minimum 10,000)

By default, there is no TPS limit. You can request a TPS limit if your ad decision server (ADS) requires it, but the limit must be greater than 10,000 TPS. MediaTailor will not exceed your specified limit, but does not guarantee consistent throughput up to that limit. Your ad decision server will tell you what TPS limits it can support.

## In-order beaconing
<a name="ad-reporting-server-side-in-order-beaconing"></a>

MediaTailor automatically maintains sequential delivery of ad tracking events. The system preserves beacon ordering even when network issues, retries, or traffic management occur. This ensures measurement partners receive events in the correct order for accurate analytics.

The system follows the standard industry beacon sequence:

1. **Start events** - Fire when ad playback begins

1. **First quartile events** - Fire at 25% ad completion

1. **Midpoint events** - Fire at 50% ad completion

1. **Third quartile events** - Fire at 75% ad completion

1. **Completion events** - Fire when ads finish

These features work together automatically:
+ Beacons are held during throttling to maintain proper order
+ Each measurement partner domain has separate event queues to prevent disruption during rate adjustments
+ Deduplication tracks event type and timeline position while maintaining chronological order

# Client-side ad tracking
<a name="ad-reporting-client-side"></a>

Using the AWS Elemental MediaTailor client-side tracking API, you can incorporate player controls during ad breaks in streaming workflows. In client-side tracking, the player or client emits tracking events, such as impression and quartile ad beaconing, to the Ad Decision Server (ADS) and other ad-verification entities. These events track both the overall ad break status and the individual ad avails within each break. For more information about impression and quartile (ADS) and other ad-verification entities. For more information about impression and quartile ad beaconing, see [Client-side beaconing](ad-reporting-client-side-beaconing.md). For more information about ADS and other ad-verification entities, see [Client-side ad-tracking integrations](ad-reporting-client-side-ad-tracking-integrations.md).

For information about passing player parameters and session data to the ADS for client-side tracking, see [MediaTailor player variables for ADS requests](variables-player.md) and [MediaTailor session variables for ADS requests](variables-session.md).

Client-side tracking enables functionality like the following: 
+ Ad-break countdown timers - For more information, see [Ad countdown timer](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-ad-countdown-timer).
+ Ad click-through - For more information, see [Ad click-through](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-ad-clickthrough).
+ Display of companion ads - For more information, see [Companion ads](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-companion-ads).
+ Skippable ads - For more information, see [Skippable ads](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-skippable-ads).
+ Display of VAST icons for privacy compliance - For more information, see [Icons for Google Why This Ad (WTA)](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-google-wta).
+ Control of player scrubbing during ads - For more information, see [Scrubbing](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-scrubbing).

Using the MediaTailor client-side tracking API, you can send metadata to the playback device that enables functionality in addition to client-side tracking:

## Client-side reporting workflow
<a name="ad-reporting-client-side-workflow"></a>

The following diagram shows the complete client-side reporting workflow from session initialization through ad playback and beaconing:

![\[MediaTailor client-side reporting sequence diagram showing the interaction between the video player, MediaTailor, Ad Decision Server, content origin, and ad verification services during the complete workflow from session initialization through ad playback and beaconing.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/tracking_flow.png)


The client-side reporting workflow includes the following steps:

1. **Session initialization** - The video player sends a POST request to the MediaTailor session endpoint with JSON metadata including `adsParams`, origin tokens, and session features. MediaTailor responds with `manifestUrl` and `trackingUrl` for the session.

1. **Manifest request and ad decision** - The player requests the personalized manifest from MediaTailor. MediaTailor requests the original content manifest from the origin, makes an ad request to the Ad Decision Server (ADS) using player parameters, receives a VAST response with ad metadata, and delivers a personalized manifest with ad markers to the player.

1. **Tracking data retrieval** - The player polls the tracking URL at regular intervals (matching target duration for HLS or minimum update period for DASH). MediaTailor returns JSON tracking metadata containing avails, ads, tracking events, beacon URLs, and ad verification data.

1. **Ad playback and beaconing** - During ad breaks, the player parses the tracking metadata, fires impression beacons when ads begin rendering, fires quartile beacons (start, firstQuartile, midpoint, thirdQuartile, complete) at appropriate timing, loads and executes ad verification JavaScript if required, and sends viewability/verification events to third-party verification services.

1. **Continuous polling** - The player continues polling the tracking URL throughout the session to receive updated metadata for upcoming ad breaks and dynamic content.

This workflow enables advanced features such as ad countdown timers, click-through functionality, companion ads, skippable ads, and VAST icon display for privacy compliance.

**Topics**
+ [Client-side reporting workflow](#ad-reporting-client-side-workflow)
+ [Enabling client-side tracking](#ad-reporting-client-side-enabling)
+ [Ad server parameters](#ad-reporting-client-side-ad-server-parameters)
+ [Origin interaction query parameters](#ad-reporting-client-side-origin-interaction-query-parameters)
+ [Session-configured features](#ad-reporting-client-side-session-configured-features)
+ [Best practices for client-side tracking](#ad-reporting-client-side-best-practices)
+ [Client-side ad-tracking schema and properties](ad-reporting-client-side-ad-tracking-schema.md)
+ [Ad-tracking activity timing](ad-reporting-client-side-ad-tracking-schema-activity-timing.md)
+ [Player controls and functionality for client-side ad tracking](ad-reporting-client-side-ad-tracking-schema-player-controls.md)
+ [Client-side beaconing](ad-reporting-client-side-beaconing.md)
+ [Hybrid mode with server-side ad beacons](ad-reporting-hybrid-mode.md)
+ [Client-side ad-tracking integrations](ad-reporting-client-side-ad-tracking-integrations.md)
+ [Paging through ad beacons with GetTracking](#gettracking)

## Enabling client-side tracking
<a name="ad-reporting-client-side-enabling"></a>

You enable client-side tracking for each session. The player makes an HTTP `POST` to the MediaTailor configuration's session-initialization prefix endpoint. Optionally, the player can send additional metadata for MediaTailor to use when making ad calls, calling the origin for a manifest, and invoking or disabling MediaTailor features at the session level.

The following example shows the structure of the JSON metadata:

```
{
  "adsParams": {                  # 'adsParams' is case sensitive
    "param1": "value1",           # key is not case sensitive
    "param2": "value2",           # Values can contain spaces. For example, 'value 2' is an allowed value. 
    },
  "origin_access_token":"abc123", # this is an example of a query parameter designated for the origin
  "overlayAvails":"on"            # 'overlayAvails' is case sensitive. This is an example of a feature that is enabled at the session level.
}
```

Use the MediaTailor console or API to configure the ADS request template URL to reference these parameters. In the following example, `player_params.param1` are the player parameters for `param1`, and `player_params.param2` are the player parameters for `param2`.

```
https://my.ads.com/path?param1=[player_params.param1]&param2=[player_params.param2]
```

## Ad server parameters
<a name="ad-reporting-client-side-ad-server-parameters"></a>

At the topmost level of the JSON structure is an `adsParams` JSON object. Inside this object are key/value pairs that MediaTailor can read and send to the ad server in all session requests. MediaTailor supports the following ad servers:
+ Google Ad Manager 
+ SpringServe 
+ FreeWheel 
+ Publica 

## Origin interaction query parameters
<a name="ad-reporting-client-side-origin-interaction-query-parameters"></a>

Any reserved key/value pairs within the topmost level of the JSON structure, such as `adsParams`, `availSuppression`, and `overlayAvails`, aren’t added to the origin request URL in the form of query parameters. Every session manifest request that MediaTailor makes to the origin contains these query parameters. The origin ignores extraneous query parameters. For example, MediaTailor can use the key/value pairs to send access tokens to the origin.

## Session-configured features
<a name="ad-reporting-client-side-session-configured-features"></a>

Use the session-initialization JSON structure to enable, disable, or override MediaTailor features such as `overlayAvails`, `availSuppression`, and `adSignaling`. Any feature configurations passed during session initialization override the setting at the MediaTailor configuration level.

**Note**  
The metadata submitted to MediaTailor at session initialization is immutable, and additional metadata cannot be added for the duration of the session. Use SCTE-35 markers to carry data that changes during the session. For more information, see [MediaTailor session variables for ADS requests](variables-session.md).

**Example : Performing client-side ad tracking for HLS**  

```
POST mediatailorURL/v1/session/hashed-account-id/origin-id/asset-id.m3u8

        {
            "adsParams": {
               "deviceType": "ipad"   # This value does not change during the session.
               "uid": "abdgfdyei-2283004-ueu"                     
           }
        }
```

**Example : Performing client-side ad tracking for DASH**  

```
POST mediatailorURL/v1/session/hashed-account-id/origin-id/asset-id.mpd

        {
            "adsParams": {
               "deviceType": "androidmobile",
               "uid": "xjhhddli-9189901-uic" 
           }
        }
```

### Reporting mode parameter
<a name="session-initialization-reporting-mode"></a>

You can specify the reporting mode when initializing a session by including the `reportingMode` parameter in the request body. This parameter controls whether MediaTailor performs client-side or server-side ad tracking for the session.
+ `client` - The player performs ad tracking and sends beacons to the ad server. This is the default mode if no `reportingMode` is specified.
+ `server` - MediaTailor performs server-side ad tracking and sends beacons directly to the ad server.

**Example Session initialization with server-side reporting mode**  

```
POST mediatailorURL/v1/session/hashed-account-id/origin-id/asset-id.m3u8

        {
            "adsParams": {
               "deviceType": "ipad",
               "uid": "abdgfdyei-2283004-ueu"                     
           },
           "reportingMode": "server"
        }
```

**Example Session initialization with client-side reporting mode (explicit)**  

```
POST mediatailorURL/v1/session/hashed-account-id/origin-id/asset-id.mpd

        {
            "adsParams": {
               "deviceType": "androidmobile",
               "uid": "xjhhddli-9189901-uic" 
           },
           "reportingMode": "client"
        }
```

**Note**  
The `reportingMode` parameter is set at session initialization and cannot be changed during the session. If no `reportingMode` is specified, MediaTailor defaults to client-side reporting to maintain backward compatibility.

A successful response is an HTTP `200` with a response body. The body contains a JSON object with a `manifestUrl` and a `trackingUrl` key. The values are relative URLs that the player can use for both playback and ad-event tracking purposes.

```
{
  "manifestUrl": "/v1/dashmaster/hashed-account-id/origin-id/asset-id.m3u8?aws.sessionId=session-id",
  "trackingUrl": "/v1/tracking/hashed-account-id/origin-id/session-id"
}
```

For more information on the client-side tracking schema, see [Client-side ad-tracking schema and properties](ad-reporting-client-side-ad-tracking-schema.md).

## Best practices for client-side tracking
<a name="ad-reporting-client-side-best-practices"></a>

This section outlines the best practices for client-side tracking in MediaTailor for both live and VOD workflows.

### Live workflows
<a name="ad-reporting-client-side-best-practices-live"></a>

Poll the tracking endpoint at an interval matching every target duration for HLS, or minimum update period for DASH, in order to always have the most current ad-tracking metadata. Matching this interval is especially important in workflows where the creatives might have an interactive or overlay component. 

**Note**  
Some players support event listeners, which could be used as an alternative to polling. For example, the MediaTailor ad ID decoration feature would need to be enabled for each session. For more information, see [Ad ID decoration](ad-id-decoration.md). Using this feature puts a date range (HLS) or event element (DASH) identifier over each ad in the avail. Players can use these manifest tags as a prompt to call the MediaTailor tracking endpoint for the session.

### VOD workflows
<a name="ad-reporting-client-side-best-practices-vod"></a>

Following a successful session initialization, and after MediaTailor receives the first manifest containing media, you only need to call the tracking endpoint once.

![\[Call flow for VOD workflows. Call the client-side tracking endpoint after the session initializes and MediaTailor receives the first manifest that contains media.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/vod-workflow-best-practice.png)


### Server-guided ad insertion
<a name="ad-reporting-client-side-best-practices-sgai"></a>

Server-guided ad insertion (SGAI) sessions do not use the `GetTracking` API. Instead, when you use `aws.reportingMode=CLIENT`, MediaTailor provides tracking information in the `TRACKING` section of each asset list response when players request ad content. The session initialization response does not include a `trackingUrl`.

The asset list response for client-side tracked SGAI sessions has the following structure:

```
{
  "ASSETS": [
    { "DURATION": 20.0, "URI": "https://cdn.example.com/ad1/master.m3u8" },
    { "DURATION": 10.0, "URI": "https://cdn.example.com/ad2/master.m3u8" }
  ],
  "TRACKING": {
    ...VAST tracking events and beacon URLs for each ad...
  }
}
```

When implementing client-side tracking for SGAI methods:
+ Parse the `TRACKING` section from asset list responses rather than calling `GetTracking`
+ Use the tracking URLs provided in the asset list for ad event reporting
+ Fire tracking beacons based on actual ad playback events in the player
+ Handle tracking for each ad break independently as asset lists are fetched

**Important**  
The `TRACKING` section is only included in the asset list when `aws.reportingMode=CLIENT` is set. When server-side reporting is used (the default for SGAI), MediaTailor omits the `TRACKING` section and embeds beacon data in the ad URIs instead. For details, see [Server-side tracking with server-guided ad insertion (SGAI)](ad-reporting-server-side-sgai.md).

# Client-side ad-tracking schema and properties
<a name="ad-reporting-client-side-ad-tracking-schema"></a>

With the MediaTailor client-side ad-tracking feature, you can integrate detailed client-side ad tracking data into your player environment. The following sections cover the overall ad-tracking schema, as well as the specific properties and values that make up the schema.

## Schema
<a name="ad-reporting-client-side-ad-tracking-schema-table"></a>

The following JSON structure shows the MediaTailor client-side ad-tracking schema. This representation illustrates the nesting structure of the schema to help you understand the relationships between different parts.

For detailed information about each property, see [Properties](#ad-reporting-client-side-ad-tracking-schema-properties).

```
{
  "avails": [
    {
      "ads": [
        {
          "adID": "string",
          "adParameters": "string",
          "adSystem": "string",
          "adTitle": "string",
          "adVerifications": [
            {
              "executableResource": [
                {
                  "apiFramework": "string",
                  "type": "string",
                  "uri": "string",
                  "language": "string"
                }
              ],
              "javaScriptResource": [
                {
                  "apiFramework": "string",
                  "browserOptional": "string",
                  "uri": "string"
                }
              ],
              "trackingEvents": [
                {
                  "event": "string",
                  "uri": "string"
                }
              ],
              "vendor": "string",
              "verificationParameters": "string"
            }
          ],
          "companionAds": [
            {
              "adParameters": "string",
              "altText": "string",
              "attributes": {
                "adSlotId": "string",
                "apiFramework": "string",
                "assetHeight": "string",
                "assetWidth": "string",
                "expandedHeight": "string",
                "expandedWidth": "string",
                "height": "string",
                "id": "string",
                "pxratio": "string",
                "renderingMode": "string",
                "width": "string"
              },
              "companionClickThrough": "string",
              "companionClickTracking": "string",
              "htmlResource": "string",
              "iFrameResource": "string",
              "sequence": "string",
              "staticResource": "string",
              "trackingEvents": [
                {
                  "event": "string",
                  "uri": "string"
                }
              ]
            }
          ],
          "creativeId": "string",
          "creativeSequence": "string",
          "duration": "string",
          "durationInSeconds": number,
          "extensions": [
            {
              "type": "string",
              "content": "string"
            }
          ],
          "icons": [
            {
              "attributes": {
                "apiFramework": "string",
                "duration": "string",
                "height": "string",
                "offset": "string",
                "program": "string",
                "pxratio": "string",
                "width": "string",
                "xPosition": "string",
                "yPosition": "string"
              },
              "htmlResource": "string",
              "iconClicks": {
                "iconClickThrough": "string",
                "iconClickTracking": {
                  "id": "string"
                },
                "iconClickFallbackImages": [
                  {
                    "altText": "string",
                    "height": "string",
                    "width": "string",
                    "staticResource": {
                      "creativeType": "string",
                      "uri": "string"
                    }
                  }
                ]
              },
              "iconViewTracking": "string",
              "iFrameResource": "string",
              "staticResource": {
                "creativeType": "string",
                "uri": "string"
              }
            }
          ],
          "mediaFiles": {
            "adParameters": "string",
            "duration": "string",
            "durationInSeconds": number,
            "mediaFilesList": [
              {
                "apiFramework": "string",
                "delivery": "string",
                "height": "string",
                "maintainAspectRatio": "string",
                "mediaFileUri": "string",
                "mediaType": "string",
                "scalable": "string",
                "width": "string",
                "bitrate": "string"
              }
            ],
            "mezzanine": "string",
            "startTime": "string",
            "startTimeInSeconds": number,
            "trackingEvents": [
              {
                "beaconUrls": ["string"],
                "duration": "string",
                "durationInSeconds": number,
                "dateTime": "string",
                "eventId": "string",
                "eventType": "string",
                "startTime": "string",
                "startTimeInSeconds": number
              }
            ]
          },
          "startTime": "string",
          "startTimeInSeconds": number,
          "dateTime": "string",
          "adBreakTrackingEvents": [...],
          "vastAdId": "string"
        }
      ],
      "adType": "string",
      "availID": "string",
      "duration": "string",
      "durationInSeconds": number,
      "startTime": "string",
      "startTimeInSeconds": number,
      "dateTime": "string",
      "adMarkerDuration": "string",
      "adProgramDateTime": "string",
      "dashAvailabilityStartTime": "string",
      "hlsAnchorMediaSequenceNumber": "string"
    }
  ],
  "nonLinearAvails": [
    {
      "nonLinearAds": [...],
      "nonLinearAdsList": [...]
    }
  ],
  "nextToken": "string",
  "meta": {}
}
```

## Properties
<a name="ad-reporting-client-side-ad-tracking-schema-properties"></a>

The following table lists the properties in the client-side tracking API, their definitions, value types, and examples.


****  

| Property | Definition | Value type | Example | 
| --- | --- | --- | --- | 
|   adID  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/ad-reporting-client-side-ad-tracking-schema.html) Path: `/avails/ads/adId` VAST mapping: None  | String | 10 | 
|   adBreakTrackingEvents  |  An array that carries VMAP tracking events from the VAST response. For more information, see section 2.3.3 of the [VMAP 1.0 specification](https://www.iab.com/guidelines/vmap/). Path: `/avails/ads/adBreakTrackingEvents`  | Array |  []  | 
|   adMarkerDuration  |  The avail duration observed from the ad marker in the manifest.  | String |  30  | 
|   adParameters  |  A string of ad parameters, from the VAST VPAID, that MediaTailor passes to the player. Path: `/avails/ads/adParameters` VAST mapping: `VAST/Ad/InLine/Creatives/Creative/Linear/AdParameters`  | String |  | 
|   adProgramDateTime  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/ad-reporting-client-side-ad-tracking-schema.html)  | String |  | 
|   ads  |  An array containing the ad objects that make up the avail. The ads are listed in the order they appear in the manifest. Path: `/avails/ads`  | Array |  []  | 
|   adSystem  |  The name of the system that serves the ad.  Make sure to provide a value. If you don't provide a value, issues can arise.   | String |  myADS  | 
|   adTitle  |  The title of the ad.  | String |  ad1  | 
|   adVerifications  |  Contains the resources and metadata required to execute third-party measurement code in order to verify creative playback. For more information about this property, see section 3.16 of the [VAST 4.2 specification](https://iabtechlab.com/standards/vast/). MediaTailor supports `adVerifications` as VAST 3 extension nodes. Path: `/avails/ads/adVerifications` VAST mapping: `VAST/Ad/InLine/AdVerifications`  | Array |  []  | 
|   altText  |  The alternative text for an image of a companion ad. This text enables players with descriptive-audio support for the visually impaired to read back a description of the image. Path: `/avails/ads/companionAds/altText`  | String |  video sequence advertising sneakers  | 
|   apiFramework  |  Set to `VPAID` to tell the player that this ad is a VPAID ad. Can appear in multiple locations in the schema.  | String |  VPAID  | 
|   availID  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/ad-reporting-client-side-ad-tracking-schema.html) Path: `/avails/availID`  | String |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/ad-reporting-client-side-ad-tracking-schema.html)  | 
|   avails  |  An array containing ad-break objects, or *avails*, that are presented in the active manifest window. The avails are listed in the order they appear in the manifest. Path: `/avails`  | Array |  []  | 
|   adType  |  The type of the ad. Path: `/avails/adType` and `/avails/ads/adType`  | String |  | 
|   dateTime  |  Program date time, in ISO 8601 seconds format, for the start of the ad avail or ad. Path: `/avails/dateTime` and `/avails/ads/dateTime`  | String |  | 
|   duration  |  Length, in ISO 8601 seconds format. The response includes durations for the entire ad avail and for each ad and beacon, though beacon durations are always zero. Path: `/avails/duration` and `/avails/ads/duration`  | String | 15.015 | 
|   durationInSeconds  |  Length, in seconds format. Path: `/avails/durationInSeconds` and `/avails/ads/durationInSeconds`  | Number |  | 
|   extensions  |  Custom extensions of VAST that ad servers use. For more information about extensions, see section 3.18 of the [VAST 4.2 specification](https://iabtechlab.com/standards/vast/). Path: `/avails/ads/extensions` VAST mapping: `VAST/Ad/InLine/Extensions`  | Array | [] | 
|   icons  |  Icon elements for the ad. Path: `/avails/ads/icons` VAST mapping: `VAST/Ad/InLine/Creatives/Creative/Linear/Icons`  | Array |  | 
|   mediaFiles  |  Video and other assets that the player needs for the ad avail. Path: `/avails/ads/mediaFiles`  | Object |  | 
|   nonLinearAvails  |  Array of non-linear ad avail objects. Path: `/nonLinearAvails`  | Array |  | 
|   executableResource  |  Executable resources for verification. Path: `/avails/ads/adVerifications/executableResource` VAST mapping: `VAST/Ad/InLine/AdVerifications/Verification/ExecutableResource`  | Array |  | 
|   javaScriptResource  |  JavaScript resources for verification. Path: `/avails/ads/adVerifications/javaScriptResource` VAST mapping: `VAST/Ad/InLine/AdVerifications/Verification/JavaScriptResource`  | Array |  | 
|   trackingEvents  |  Tracking events for verification or companion ads. Path: `/avails/ads/adVerifications/trackingEvents` or `/avails/ads/companionAds/trackingEvents`  | Array |  | 
|   vendor  |  Verification vendor. Path: `/avails/ads/adVerifications/vendor` VAST mapping: `VAST/Ad/InLine/AdVerifications/Verification/@vendor`  | String |  | 
|   uri  |  URI that points to either an executable asset, a video asset, or a tracking endpoint. Path: Various locations in the schema VAST mapping: Various CDATA elements in VAST  | String | https://tracking.example.com/impression | 
|   verificationParameters  |  Verification parameters. Path: `/avails/ads/adVerifications/verificationParameters` VAST mapping: `VAST/Ad/InLine/AdVerifications/Verification/VerificationParameters`  | String |  | 
|   attributes  |  Companion ad attributes like dimensions and rendering mode. Path: `/avails/ads/companionAds/attributes`  | Object |  | 
|   companionClickThrough  |  A URL to the advertiser's page that the media player opens when the viewer clicks the companion ad. Path: `/avails/ads/companionAds/companionClickThrough` VAST mapping: `VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/CompanionClickThrough`  | String | https://aws.amazon.com/ | 
|   companionClickTracking  |  The tracking URL for the `companionClickThrough` property. Path: `/avails/ads/companionAds/companionClickTracking` VAST mapping: `VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/CompanionClickTracking`  | String | https://myads.com/beaconing/event=clicktracking | 
|   htmlResource  |  The CDATA-encoded HTML that's inserted directly within the streaming provider's HTML page. Path: `/avails/ads/companionAds/htmlResource` VAST mapping: `VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/HTMLResource`  | String | <\$1[CDATA[<\$1doctype html><html><head><meta name=\$1"viewport\$1" content=\$1"width=1, initial-scale=1.0, minimum-scale=1.0,...]]> | 
|   iFrameResource  |  The URL to an HTML resource file that the streaming provider loads into an iframe. Path: `/avails/ads/companionAds/iFrameResource` VAST mapping: `VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/iFrameResource`  | String |  | 
|   sequence  |  The sequence value specified for the creative in the VAST response. Path: `/avails/ads/companionAds/sequence`  | String | 1 | 
|   startTime  |  The time position, in ISO 8601 seconds format. For HLS, this is relative to the beginning of the playback session. For DASH, this is relative to the manifest's AST (Availability Start Time). The response includes start times for the entire ad avail and for each ad and beacon. Path: `/avails/startTime` and `/avails/ads/startTime`  | String | PT18.581355S | 
|   startTimeInSeconds  |  The time position, in seconds format. For HLS, this is relative to the beginning of the playback session. For DASH, this is relative to the manifest's AST (Availability Start Time). The response includes start times for the entire ad avail and for each ad and beacon. Path: `/avails/startTimeInSeconds` and `/avails/ads/startTimeInSeconds`  | Number | 18.581 | 
|   eventId  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/ad-reporting-client-side-ad-tracking-schema.html)  | String |  | 
|   event  |  The name of the tracking event. Path: `/avails/ads/adVerifications/trackingEvents/event` or `/avails/ads/companionAds/trackingEvents/event`  | String | impression, start, firstQuartile, midpoint, thirdQuartile, complete | 
|   beaconUrls  |  The URL where MediaTailor sends the ad beacon. Path: `/avails/ads/mediaFiles/trackingEvents/beaconUrls`  | Array |  | 
|   bitrate  |  The bitrate of the video asset. This property is not typically included for an executable asset.  | String | 2048 | 
|   companionAds  |  One or more companion ad-content specifications, each of which specifies a resource file to use. Companion ads accompany the ad avail and provide content, like a frame around the ad or a banner, to display near the video. Path: `/avails/ads/companionAds`  | Array | [] | 
|   creativeId  |  The `Id` attribute value of the `Creative` tag for the ad.  | String | creative-1 | 
|   creativeSequence  |  The sequence in which an ad should play, according to the `Ad@id` value in the VAST response.  | String | 1 | 
|   dashAvailabilityStartTime  |  For live/dynamic DASH, the `MPD@availabilityStartTime` of the origin manifest.  | String | 2022-10-05T19:38:39.263Z | 
|   delivery  |  Indicates whether a `progressive` or `streaming` protocol is being used.  | String | progressive | 
|   eventType  |  The type of beacon. Path: `/avails/ads/mediaFiles/trackingEvents/eventType`  | String | impression | 
|   height  |  The height, in pixels, of the video asset.  | String | 360 | 
|   hlsAnchorMediaSequenceNumber  |  The media-sequence number of the first/oldest media sequence seen in the HLS origin manifest.  | String | 77 | 
|   maintainAspectRatio  |  Indicates whether to maintain the video's aspect ratio while scaling.  | Boolean | true | 
|   mediaFilesList  |  Specifies the video and other assets that the player needs for the ad avail. Path: `/avails/ads/mediaFiles/mediaFilesList`  | Array | [] | 
|   mediaFileUri  |  URI that points to either an executable asset or a video asset.  | String | https://myad.com/ad/ad134/vpaid.js | 
|   mediaType  |  The MIME type of the creative or companion asset.  | String | video/mp4 | 
|   meta  |  Additional metadata for the ad.  | Object |  | 
|   mezzanine  |  The URL of the mezzanine MP4 asset, specified if the VPAID ad includes one. Path: `/avails/ads/mediaFiles/mezzanine`  | String | https://gcdn.2mdn.net/videoplayback/id/itag/ck2/file/file.mp4 | 
|   nextToken  |  The value of the token that points to the next page of results, when such a value exists.  | String | UFQzOS44NzNTXzIwMjMtMDctMzFUMTY6NTA6MDYuMzUwNjI2ODQ1Wl8x | 
|   nonLinearAds  |  Non-linear ads that appear alongside the video content.  | Array | [] | 
|   nonLinearAdsList  |  List of non-linear ads.  | Array | [] | 
|   scalable  |  Indicates whether to scale the video to other dimensions.  | Boolean | true | 
|   skipOffset  |  The time value that identifies when the player makes skip controls available to the user.  | String | 00:00:05 | 
|   staticResource  |  The URL to a static creative file that's used for the ad component. Path: `/avails/ads/companionAds/staticResource`  | String | https://very-interactive-ads.com/campaign1/file.json?c=1019113602 | 
|   vastAdId  |  The `Id` attribute value of the `Ad` tag.  | String | ad1 | 
|   width  |  The width, in pixels, of the video asset.  | String | 640 | 
|   xPosition  |  The horizontal position of an icon within the video player. Can be a specific pixel value or a position like "left" or "right". Path: `/avails/ads/icons/attributes/xPosition`  | String | left or 10 | 
|   yPosition  |  The vertical position of an icon within the video player. Can be a specific pixel value or a position like "top" or "bottom". Path: `/avails/ads/icons/attributes/yPosition`  | String | top or 10 | 
|   iconClicks  |  Contains click-through and tracking information for an icon. Path: `/avails/ads/icons/iconClicks`  | Object |  | 
|   iconClickThrough  |  A URL to the advertiser's page that the media player opens when the viewer clicks the icon. Path: `/avails/ads/icons/iconClicks/iconClickThrough`  | String | https://advertiser.com/landing-page | 
|   iconClickTracking  |  The tracking URL for the `iconClickThrough` property. Path: `/avails/ads/icons/iconClicks/iconClickTracking`  | Object |  | 
|   iconClickFallbackImages  |  An array of fallback images to display if the icon cannot be displayed. Path: `/avails/ads/icons/iconClicks/iconClickFallbackImages`  | Array |  | 
|   iconViewTracking  |  The URL for tracking when an icon is viewed. Path: `/avails/ads/icons/iconViewTracking`  | String | https://tracking.example.com/icon-view | 
|   offset  |  The time offset for when an icon should appear during ad playback. Path: `/avails/ads/icons/attributes/offset`  | String | 00:00:05 | 
|   program  |  The program or initiative associated with the icon, such as "AdChoices". Path: `/avails/ads/icons/attributes/program`  | String | AdChoices | 
|   pxratio  |  The pixel ratio for the icon or companion ad, used for high-DPI displays. Path: `/avails/ads/icons/attributes/pxratio` or `/avails/ads/companionAds/attributes/pxratio`  | String | 1 or 2 | 
|   type  |  The type of resource or extension. Path: `/avails/ads/extensions/type` or `/avails/ads/adVerifications/executableResource/type`  | String | text/javascript | 
|   content  |  The content of an extension. Path: `/avails/ads/extensions/content`  | String |  | 
|   language  |  The programming language of an executable resource. Path: `/avails/ads/adVerifications/executableResource/language`  | String | javascript | 
|   browserOptional  |  Indicates whether browser support is required for the JavaScript resource. Path: `/avails/ads/adVerifications/javaScriptResource/browserOptional`  | String | true or false | 
|   id  |  An identifier for various elements in the schema. Path: `/avails/ads/companionAds/attributes/id` or `/avails/ads/icons/iconClicks/iconClickTracking/id`  | String | companion-1 | 
|   assetHeight  |  The height of the companion ad asset. Path: `/avails/ads/companionAds/attributes/assetHeight`  | String | 250 | 
|   assetWidth  |  The width of the companion ad asset. Path: `/avails/ads/companionAds/attributes/assetWidth`  | String | 300 | 
|   expandedHeight  |  The height of the companion ad when expanded. Path: `/avails/ads/companionAds/attributes/expandedHeight`  | String | 600 | 
|   expandedWidth  |  The width of the companion ad when expanded. Path: `/avails/ads/companionAds/attributes/expandedWidth`  | String | 600 | 
|   renderingMode  |  The rendering mode for the companion ad. Path: `/avails/ads/companionAds/attributes/renderingMode`  | String | default or transparent | 
|   adSlotId  |  The ID of the ad slot where the companion ad should be displayed. Path: `/avails/ads/companionAds/attributes/adSlotId`  | String | banner-1 | 
|   creativeType  |  The MIME type of the creative asset. Path: `/avails/ads/icons/staticResource/creativeType`  | String | image/png | 

# Ad-tracking activity timing
<a name="ad-reporting-client-side-ad-tracking-schema-activity-timing"></a>

With client-side reporting, the player must emit tracking events (beacons) with a level of precision. Using the MediaTailor client-side tracking schema, you can ensure that, for every avail, ad, companion, overlay, and tracking events, timing and duration information is present, and in different forms.

Use the following MediaTailor key/value pairs for the player to accurately reconcile ad-event activities, such as tracking events, with playback position:
+ [startTime](ad-reporting-client-side-ad-tracking-schema.md#property-starttime) 
+  [startTimeInSeconds](ad-reporting-client-side-ad-tracking-schema.md#property-starttimeinseconds) 
+  [adProgramDateTime](ad-reporting-client-side-ad-tracking-schema.md#property-adprogramdatetime) 
+  [adID](ad-reporting-client-side-ad-tracking-schema.md#property-adid)/[eventId](ad-reporting-client-side-ad-tracking-schema.md#property-eventid) 

HLS and DASH implement the value of `startTime` and `startTimeInSeconds` differently:
+ HLS - The `startTime` values are relative to the beginning of the playback session. The beginning of the playback session is defined as time zero. The ad's `startTime` is the sum of the cumulative values of all the `EXT-INF` segment durations leading up to the avail. The media-sequence number of the segment that the ad or tracking event falls on also corresponds to the `adId` or `eventId` in the client-side tracking response.
+ DASH:
  + Live/dynamic manifests - The `startTime` values are relative to the `MPD@availabilityStartTime` of the DASH manifest. The `MPD@avaibilityStartTime` is a timing anchor for all MediaTailor sessions that consume the stream.
  + VOD/static manifests - The `startTime` values are relative to the beginning of the playback session. The beginning of the playback session is defined as time zero. Each ad inside the avail is contained inside its own `Period` element. The `Period` element has a `@start` attribute with a value that's the same as the `startTime` values in the client-side tracking payload. The `PeriodId` also corresponds to the `adId` or `eventId` in the client-side tracking response.

**Example : HLS**  
In the following example, the MediaTailor session started, and the following manifest is the first one served to the client:  

```
#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:4603263
#EXT-X-DISCONTINUITY-SEQUENCE:0
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:23.295678Z
#EXTINF:4.010667,
https://123.cloudfront.net/out/v1/index_1_34.ts
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:27.306345Z
#EXTINF:4.010667,
https://123.cloudfront.net/out/v1/index_1_35.ts
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:31.317012Z
#EXTINF:4.010667,
https://123.cloudfront.net/out/v1/index_1_36.ts
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:35.327679Z
#EXTINF:4.010667,
https://123.cloudfront.net/out/v1/index_1_37.ts
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:39.338346Z
#EXTINF:2.538667,
https://123.cloudfront.net/out/v1/index_1_38.ts
#EXT-X-DISCONTINUITY
#EXT-X-KEY:METHOD=NONE
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:41.453Z
#EXTINF:2.0,
https://123.cloudfront.net/tm/asset_1080_4_8_00001.ts
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:43.453Z
#EXTINF:2.0,
https://123.cloudfront.net/tm/asset_1080_4_8_00002.ts
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:45.453Z
#EXTINF:2.0,
https://123.cloudfront.net/tm/asset_1080_4_8_00003.ts
```
In the client-side tracking JSON payload, the following values apply:  
+  `startTime`: `"PT18.581355S"` 
+  `startTimeInSeconds`: `18.581` 
+  `availProgramDateTime`: `"2023-05-03T21:24:41.453Z"` 
+  `adId`: `4603269` 

**Example : DASH**  
In the following example, the MediaTailor session gets a midroll in the manifest. Note that the `@start` attribute value of the second period, which is the ad period, has a value that's relative to the `MPD@availabilityStartTime` value. This value is the one that MediaTailor writes into the client-side tracking response `startTime` fields, for all sessions.  

```
<?xml version="1.0" encoding="UTF-8"?>
<MPD availabilityStartTime="2022-10-05T19:38:39.263Z" minBufferTime="PT10S" minimumUpdatePeriod="PT2S" profiles="urn:mpeg:dash:profile:isoff-live:2011" publishTime="2023-05-03T22:06:48.411Z" suggestedPresentationDelay="PT10S" timeShiftBufferDepth="PT1M30S" 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://123.channel-assembly.mediatailor.us-west-2.amazonaws.com/v1/channel/my-channel/</BaseURL>
    <Location>https://123.cloudfront.net/v1/dash/94063eadf7d8c56e9e2edd84fdf897826a70d0df/MediaTailor-Live-HLS-DASH/channel/channel1/dash.mpd?aws.sessionId=794a15e0-2a7f-4941-a537-9d71627984e5</Location>
    <Period id="1683151479166_1" start="PT5042H25M59.903S" xmlns="urn:mpeg:dash:schema:mpd:2011">
        <BaseURL>https://123.cloudfront.net/out/v1/f1a946be8efa45b0931ea35c9055fb74/ddb73bf548a44551a0059c346226445a/eaa5485198bf497284559efb8172425e/</BaseURL>
        <AdaptationSet ...>
            ...
        </AdaptationSet>
    </Period>
    <Period id="1683151599194_1_1" start="PT5042H27M59.931S">
        <BaseURL>https://123.cloudfront.net/tm/94063eadf7d8c56e9e2edd84fdf897826a70d0df/fpc5omz5wzd2rdepgieibp23ybyqyrme/</BaseURL>
        <AdaptationSet ...>
            ...
        </AdaptationSet>
    </Period>
</MPD>
```
In the client-side tracking JSON payload, the following values apply:  
+  `startTime`: `"PT5042H27M59.931S"` 
+  `startTimeInSeconds`: `18152879.931` 
+  `availProgramDateTime`: *null* 
+  `adId`: `1683151599194_1_1` 

# Player controls and functionality for client-side ad tracking
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls"></a>

MediaTailor client-side tracking metadata supports various player controls and functionality. The following list describes popular player controls.

**Topics**
+ [Scrubbing](#ad-reporting-client-side-ad-tracking-schema-player-controls-scrubbing)
+ [Ad countdown timer](#ad-reporting-client-side-ad-tracking-schema-player-controls-ad-countdown-timer)
+ [Skippable ads](#ad-reporting-client-side-ad-tracking-schema-player-controls-skippable-ads)
+ [Ad click-through](#ad-reporting-client-side-ad-tracking-schema-player-controls-ad-clickthrough)
+ [Companion ads](#ad-reporting-client-side-ad-tracking-schema-player-controls-companion-ads)
+ [Interactive ads (SIMID)](#ad-reporting-client-side-ad-tracking-schema-player-controls-simid-ads)
+ [Interactive ads (VPAID)](#ad-reporting-client-side-ad-tracking-schema-player-controls-vpaid-ads)
+ [Icons for Google Why This Ad (WTA)](#ad-reporting-client-side-ad-tracking-schema-player-controls-google-wta)

## Scrubbing
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-scrubbing"></a>

To enhance the playback experience, the player can display ad positions in the playback timeline. MediaTailor makes these ad positions available in the form of `startTimeInSeconds` values in the client-side tracking response.

**Note**  
Some streaming providers prevent scrubbing past an ad position.

![\[Screenshot showing MediaTailor marking positions in the video timeline where ads play.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/scrubbing.png)


The following client-side tracking payload JSON response shows the avail (ad break) start time inside the root JSON object of the avails array. The player uses this data to show the location of the ad break on the player timeline, at 28 seconds.

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [...],
      "availId": "7",
      "availProgramDateTime": null,
      "duration": "PT30S",
      "durationInSeconds": 30,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT28S",
      "startTimeInSeconds": 28
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQxMk0zNC44NjhTXzIwMjMtMDctMjFUMjA6MjM6MDcuNzc1NzE2MzAyWl8x",
  "nonLinearAvails": []
}
```

## Ad countdown timer
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-ad-countdown-timer"></a>

With MediaTailor you can use an ad countdown timer to help keep your audience engaged during ad-break viewing. The audience can use the timer to understand when the ad break ends and their program resumes.

![\[Screenshot showing MediaTailor displaying an ad countdown timer, which tells the audience the time remaining until their program resumes.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/ad-countdown-timer.png)


The elements in the client-side tracking metadata that play a role in the ad countdown timer are `startTime`, `startTimeInSeconds`, `duration`, and `durationInSeconds`. The player uses this metadata, along with the session's elapsed time that it tracks separately, to determine when to display the timer and the value it should be counting down from.

The following client-side tracking payload JSON response shows the information needed to display an ad countdown timer.

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [...],
      "availId": "7",
      "availProgramDateTime": null,
      "duration": "PT30S",
      "durationInSeconds": 30,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT28S",
      "startTimeInSeconds": 28
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQxMk0zNC44NjhTXzIwMjMtMDctMjFUMjA6MjM6MDcuNzc1NzE2MzAyWl8x",
  "nonLinearAvails": []
}
```

When the session's elapsed time reaches the avail's start time, the player displays a countdown timer with a value that matches the avail's duration. The countdown-timer value decreases as the elapsed time progresses beyond the avail's start time.

**Example formula: Countdown timer for HLS (live and VOD) and DASH (VOD)**  
+ `session_start_time` = the sum of all `EXT-INF` duration values - the duration value of the three newest `EXT-INF` media sequences
+ timer value = `duration` - (`session_elapsed_time` - `startTime`)

![\[Diagram showing the calculation of the ad countdown timer, based on the session's start time and avail's start time, for HLS (live and VOD) and DASH (VOD) manifests.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/ad-countdown-timer-hls-dash-vod.png)


**Example formula: Countdown timer for DASH (live)**  
+ `session_start_time` = (newest segment's `startTime` \$1 `duration`) / `timescale` - `MPD@suggestedPresentationDelay`
+ timer value = `duration` - (`session_elapsed_time` - `startTime`)

![\[Diagram showing the calculation of the ad countdown timer, based on the session's start time and avail's start time, for live DASH manifests.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/ad-countdown-timer-dash-live.png)


## Skippable ads
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-skippable-ads"></a>

*Skippable ads* are ad spots that allow the viewer to skip some of the ad to resume viewing the program. In VAST, the `Linear@skipOffset` attribute identifies a skippable ad. 

The following VAST response shows how to use a skippable ad:

```
<?xml version="1.0" encoding="UTF-8"?>
<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
  <Ad>
    <InLine>
      ...
      <Creatives>
        <Creative id="1" sequence="1">
          <Linear skipoffset="00:00:05">
            <Duration>00:00:15</Duration>
            <MediaFiles>
              <MediaFile id="EMT" delivery="progressive" width="640" height="360" type="video/mp4" bitrate="143" scalable="true" maintainAspectRatio="true"><![CDATA[https://ads.com/file.mp4]]></MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
      ...
    </InLine>
  </Ad>
</VAST>
```

The following client-side tracking payload JSON response shows the ad metadata inside the `ads` array. The array contains the `skipOffset` value that MediaTailor obtained from the VAST response.

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "1",
          "adParameters": "",
          "adProgramDateTime": "2023-07-31T16:11:40.693Z",
          "adSystem": "2.0",
          "adTitle": "AD-skiing-15",
          "adVerifications": [],
          "companionAds": [...],
          "creativeId": "1",
          "creativeSequence": "1",
          "duration": "PT15.015S",
          "durationInSeconds": 15.015,
          "extensions": [],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": "00:00:05",
          "startTime": "PT9.943S",
          "startTimeInSeconds": 9.943,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://adserverbeaconing.com/v1/impression"
              ],
              "duration": "PT15.015S",
              "durationInSeconds": 15.015,
              "eventId": "2697726",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT9.943S",
              "startTimeInSeconds": 9.943
            }
          ],
          "vastAdId": ""
        }
      ],
      "availId": "2697726",
      "availProgramDateTime": "2023-07-31T16:11:40.693Z",
      "duration": "PT15.015S",
      "durationInSeconds": 15.015,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT9.943S",
      "startTimeInSeconds": 9.943
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "",
  "nonLinearAvails": []
}
```

## Ad click-through
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-ad-clickthrough"></a>

Click-through URIs allow advertisers to measure how successful an ad is in capturing viewers' attention. After a viewer clicks the active video frame of an ad in progress, a web browser opens the URI for the advertiser's home page or campaign landing page. The player developer determines the click behavior, such as overlaying a button or label on the ad video, with a message to click to learn more. Player developers often pause the ad's video after viewers click on the active video frame.

![\[Screenshot of an ad click-through in a video player. Viewers click the video frame. The player pauses the video, then opens a web browser to take the viewer to the advertiser’s home page or campaign landing page.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/ad-clickthrough.png)


MediaTailor can parse and make available any linear video click-through event URLs returned in the VAST response. The following VAST response shows an ad click-through example.

```
<?xml version="1.0" encoding="UTF-8"?>
<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
  <Ad>
    <InLine>
      ...
      <Creatives>
        <Creative id="1" sequence="1">
          <Linear>
            <Duration>00:00:15</Duration>
            <MediaFiles>
              <MediaFile id="EMT" delivery="progressive" width="1280" height="720" type="video/mp4" bitrate="143" scalable="true" maintainAspectRatio="true"><![CDATA[https://ads.com/file.mp4]]></MediaFile>
            </MediaFiles>
            <VideoClicks>
              <ClickThrough id="EMT"><![CDATA[https://aws.amazon.com]]></ClickThrough>
              <ClickTracking id="EMT"><![CDATA[https://myads.com/beaconing/event=clicktracking]]></ClickTracking>
            </VideoClicks>
          </Linear>
        </Creative>
      </Creatives>
      ...
    </InLine>
  </Ad>
</VAST>
```

The following client-side tracking payload JSON response shows how MediaTailor displays the click-through and click-tracking URLs inside the `trackingEvents` array. The `clickThrough` event type represents the click-through ad, and the `clickTracking` event type represents the click-tracking URL.

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "1",
          "adParameters": "",
          "adProgramDateTime": "2023-07-31T16:53:40.577Z",
          "adSystem": "2.0",
          "adTitle": "1",
          "adVerifications": [],
          "companionAds": [],
          "creativeId": "00006",
          "creativeSequence": "1",
          "duration": "PT14.982S",
          "durationInSeconds": 14.982,
          "extensions": [],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": null,
          "startTime": "PT39.339S",
          "startTimeInSeconds": 39.339,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://myads.com/beaconing/event=impression"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698188",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            },
            {
              "beaconUrls": [
                "https://aws.amazon.com"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698188",
              "eventProgramDateTime": null,
              "eventType": "clickThrough",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            },
            {
              "beaconUrls": [
                "https://myads.com/beaconing/event=clicktracking"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698795",
              "eventProgramDateTime": null,
              "eventType": "clickTracking",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            }
          ],
          "vastAdId": ""
        }
      ],
      "availId": "2698188",
      "availProgramDateTime": "2023-07-31T16:53:40.577Z",
      "duration": "PT14.982S",
      "durationInSeconds": 14.982,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT39.339S",
      "startTimeInSeconds": 39.339
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQzOS4zMzlTXzIwMjMtMDctMzFUMTY6NTQ6MDQuODA1Mzk2NTI5Wl8x",
  "nonLinearAvails": []
}
```

## Companion ads
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-companion-ads"></a>

A *companion ad* appears alongside a linear creative. Use companion ads to increase the effectiveness of an ad spot by displaying product, logo, and brand information. The display ad can feature Quick Response (QR) codes and clickable areas to promote audience engagement.

MediaTailor supports companion ads in the VAST response. It can pass through metadata from `StaticResource`, `iFrameResource`, and `HTMLResource` nodes, respectively.

The following VAST response shows an example location and format of the linear ad and companion ad.

```
<?xml version="1.0" encoding="UTF-8"?>
<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
  <Ad>
    <InLine>
      ...
      <Creatives>
        <Creative id="1" sequence="1">
          <Linear>
            <Duration>00:00:10</Duration>
            <MediaFiles>
              <MediaFile id="EMT" delivery="progressive" width="640" height="360" type="video/mp4" bitrate="143" scalable="true" maintainAspectRatio="true"><![CDATA[https://ads.com/file.mp4]]></MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
        <Creative id="2" sequence="1">
          <CompanionAds>
            <Companion id="2" width="300" height="250">
              <StaticResource creativeType="image/png"><![CDATA[https://emt.com/companion/9973499273]]></StaticResource>
              <TrackingEvents>
                <Tracking event="creativeView"><![CDATA[https://beacon.com/1]]></Tracking>
              </TrackingEvents>
              <CompanionClickThrough><![CDATA[https://beacon.com/2]]></CompanionClickThrough>
            </Companion>
            <Companion id="3" width="728" height="90">
              <StaticResource creativeType="image/png"><![CDATA[https://emt.com/companion/1238901823]]></StaticResource>
              <TrackingEvents>
                <Tracking event="creativeView"><![CDATA[https://beacon.com/3]]></Tracking>
              </TrackingEvents>
              <CompanionClickThrough><![CDATA[https://beacon.com/4]]></CompanionClickThrough>
            </Companion>
          </CompanionAds>
        </Creative>
      </Creatives>
      ...
    </InLine>
  </Ad>
</VAST>
```

The data appears in the client-side tracking response in the `/avail/x/ads/y/companionAds` list. Each linear creative can contain up to 6 companion ads. As shown in the example below, the companion ads appear in a list

**Note**  
As a best practice, application developers should implement logic to explicitly remove or unload the companion ad at the end of the creative.

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "0",
          "adParameters": "",
          "adProgramDateTime": null,
          "adSystem": "EMT",
          "adTitle": "sample",
          "adVerifications": [],
          "companionAds": [
            {
              "adParameters": null,
              "altText": null,
              "attributes": {
                "adSlotId": null,
                "apiFramework": null,
                "assetHeight": null,
                "assetWidth": null,
                "expandedHeight": null,
                "expandedWidth": null,
                "height": "250",
                "id": "2",
                "pxratio": null,
                "renderingMode": null,
                "width": "300"
              },
              "companionClickThrough": "https://beacon.com/2",  
              "companionClickTracking": null,
              "htmlResource": null,
              "iFrameResource": null,
              "sequence": "1",
              "staticResource": "https://emt.com/companion/9973499273",
              "trackingEvents": [
                {
                  "beaconUrls": [
                    "https://beacon.com/1"
                  ],
                  "eventType": "creativeView"
                }
              ]
            },
            {
              "adParameters": null,
              "altText": null,
              "attributes": {
                "adSlotId": null,
                "apiFramework": null,
                "assetHeight": null,
                "assetWidth": null,
                "expandedHeight": null,
                "expandedWidth": null,
                "height": "90",
                "id": "3",
                "pxratio": null,
                "renderingMode": null,
                "width": "728"
              },
              "companionClickThrough": "https://beacon.com/4",
              "companionClickTracking": null,
              "htmlResource": null,
              "iFrameResource": null,
              "sequence": "1",
              "staticResource": "https://emt.com/companion/1238901823",
              "trackingEvents": [
                {
                  "beaconUrls": [
                    "https://beacon.com/3"
                  ],
                  "eventType": "creativeView"
                }
              ]
            }
          ],
          "creativeId": "1",
          "creativeSequence": "1",
          "duration": "PT10S",
          "durationInSeconds": 10,
          "extensions": [],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": null,
          "startTime": "PT0S",
          "startTimeInSeconds": 0,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://beacon.com/impression/1"
              ],
              "duration": "PT10S",
              "durationInSeconds": 10,
              "eventId": "0",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT0S",
              "startTimeInSeconds": 0
            }
          ],
          "vastAdId": ""
        }
      ],
      "availId": "0",
      "availProgramDateTime": null,
      "duration": "PT10S",
      "durationInSeconds": 10,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT0S",
      "startTimeInSeconds": 0
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQxMFNfMjAyMy0wNy0wNlQyMToxMDowOC42NzQ4NDA1NjJaXzE%3D",
  "nonLinearAvails": []
}
```

## Interactive ads (SIMID)
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-simid-ads"></a>

*SecureInteractive Media Interface Definition* (SIMID) is a standard for interactive advertising that was introduced in the VAST 4.x standard from the Interactive Advertising Bureau (IAB). SIMID decouples the loading of interactive elements from the primary linear creative on the player, referencing both in the VAST response. MediaTailor stitches in the primary creative to maintain the playback experience, and places metadata for the interactive components in the client-side tracking response.

In the following example VAST 4 response, the SIMID payload is inside the `InteractiveCreativeFile` node.

```
<?xml version="1.0"?>
<VAST xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
  <Ad id="1234567">
    <InLine>
      <AdSystem>SampleAdSystem</AdSystem>
      <AdTitle>Linear SIMID Example</AdTitle>
      <Description>SIMID example</Description>
      <Error>https://www.beacons.com/error</Error>
      <Impression>https://www.beacons.com/impression</Impression>
      <Creatives>
        <Creative sequence="1">
          <Linear>
            <Duration>00:00:15</Duration>
            <TrackingEvents>
                ...
            </TrackingEvents>
            <VideoClicks>
              <ClickThrough id="123">https://aws.amazon.com</ClickThrough>
              <ClickTracking id="123">https://www.beacons.com/click</ClickTracking>
            </VideoClicks>
            <MediaFiles>
              <MediaFile delivery="progressive" type="video/mp4">
                                https://interactive-ads.com/interactive-media-ad-sample/media/file.mp4
                            </MediaFile>
              <InteractiveCreativeFile type="text/html" apiFramework="SIMID" variableDuration="true">
                                https://interactive-ads.com/interactive-media-ad-sample/sample_simid.html
                            </InteractiveCreativeFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>
```

In the following VAST 3 response, the SIMID payload is inside the `Extensions` node.

```
<?xml version="1.0"?>
<VAST xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
  <Ad id="1234567">
    <InLine>
      <AdSystem>SampleAdSystem</AdSystem>
      <AdTitle>Linear SIMID Example</AdTitle>
      <Description>SIMID example</Description>
      <Impression>https://www.beacons.com/impression</Impression>
      <Creatives>
        <Creative id="1" sequence="1">
          <Linear>
            <Duration>00:00:15</Duration>
            <TrackingEvents>
                ...
            </TrackingEvents>
            <VideoClicks>
              <ClickThrough id="123">https://aws.amazon.com</ClickThrough>
              <ClickTracking id="123">https://myads.com/beaconing/event=clicktracking</ClickTracking>
            </VideoClicks>
            <MediaFiles>
              <MediaFile delivery="progressive" type="video/mp4">
                                https://interactive-ads.com/interactive-media-ad-sample/media/file.mp4
                            </MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
      <Extensions>
        <Extension type="InteractiveCreativeFile">
          <InteractiveCreativeFile type="text/html" apiFramework="SIMID" variableDuration="true">
            https://interactive-ads.com/interactive-media-ad-sample/sample_simid.html
          </InteractiveCreativeFile>
        </Extension>
      </Extensions>
    </InLine>
  </Ad>
</VAST>
```

In the following client-side tracking response, the SIMID data appears in the `/avails/x/ads/y/extensions` list.

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "1",
          "adParameters": "",
          "adProgramDateTime": "2023-07-31T16:53:40.577Z",
          "adSystem": "2.0",
          "adTitle": "Linear SIMID Example",
          "adVerifications": [],
          "companionAds": [],
          "creativeId": "1",
          "creativeSequence": "1",
          "duration": "PT14.982S",
          "durationInSeconds": 14.982,
          "extensions": [
            {
              "content": "<InteractiveCreativeFile type=\"text/html\" apiFramework=\"SIMID\" variableDuration=\"true\">\nhttps://interactive-ads.com/interactive-media-ad-sample/sample_simid.html</InteractiveCreativeFile>",
              "type": "InteractiveCreativeFile"
            }
          ],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": null,
          "startTime": "PT39.339S",
          "startTimeInSeconds": 39.339,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://myads.com/beaconing/event=impression"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698188",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            },
            {
              "beaconUrls": [
                "https://aws.amazon.com"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698188",
              "eventProgramDateTime": null,
              "eventType": "clickThrough",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            },
            {
              "beaconUrls": [
                "https://myads.com/beaconing/event=clicktracking"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698795",
              "eventProgramDateTime": null,
              "eventType": "clickTracking",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            }
          ],
          "vastAdId": ""
        }
      ],
      "availId": "2698188",
      "availProgramDateTime": "2023-07-31T16:53:40.577Z",
      "duration": "PT14.982S",
      "durationInSeconds": 14.982,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT39.339S",
      "startTimeInSeconds": 39.339
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQzOS4zMzlTXzIwMjMtMDctMzFUMTY6NTQ6MDQuODA1Mzk2NTI5Wl8x",
  "nonLinearAvails": []
}
```

## Interactive ads (VPAID)
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-vpaid-ads"></a>

The *Video Player Ad Interface Definition* (VPAID) specifies the protocol between the ad and the video player that enables ad interactivity and other functionality. For live streams, MediaTailor supports the VPAID format by stitching slate segments in for the duration of the avail, and placing metadata for the VPAID creatives in the client-side tracking response that the video player consumes. The player downloads the VPAID files and plays the linear creative and executes the client's scripts. The player should *not* ever play the slate segments.

**Note**  
VPAID is deprecated as of VAST 4.1.

![\[Diagram of VPAID ad playback. MediaTailor stitches slate segments for the avail duration in the content timeline. The player switches to the VPAID asset for the avail duration.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/interactive-ads-vpaid.png)


The following example shows the VPAID content in the VAST response.

```
<?xml version="1.0"?>
<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
  <Ad id="1234567">
    <InLine>
      <AdSystem>GDFP</AdSystem>
      <AdTitle>VPAID</AdTitle>
      <Description>Vpaid Linear Video Ad</Description>
      <Error>http://www.example.com/error</Error>
      <Impression>http://www.example.com/impression</Impression>
      <Creatives>
        <Creative sequence="1">
          <Linear>
            <Duration>00:00:00</Duration>
            <TrackingEvents>
              <Tracking event="start">http://www.example.com/start</Tracking>
              <Tracking event="firstQuartile">http://www.example.com/firstQuartile</Tracking>
              <Tracking event="midpoint">http://www.example.com/midpoint</Tracking>
              <Tracking event="thirdQuartile">http://www.example.com/thirdQuartile</Tracking>
              <Tracking event="complete">http://www.example.com/complete</Tracking>
              <Tracking event="mute">http://www.example.com/mute</Tracking>
              <Tracking event="unmute">http://www.example.com/unmute</Tracking>
              <Tracking event="rewind">http://www.example.com/rewind</Tracking>
              <Tracking event="pause">http://www.example.com/pause</Tracking>
              <Tracking event="resume">http://www.example.com/resume</Tracking>
              <Tracking event="fullscreen">http://www.example.com/fullscreen</Tracking>
              <Tracking event="creativeView">http://www.example.com/creativeView</Tracking>
              <Tracking event="acceptInvitation">http://www.example.com/acceptInvitation</Tracking>
            </TrackingEvents>
            <AdParameters><![CDATA[ {"videos":[ {"url":"https://my-ads.com/interactive-media-ads/media/media_linear_VPAID.mp4","mimetype":"video/mp4"}]} ]]></AdParameters>
            <VideoClicks>
              <ClickThrough id="123">http://google.com</ClickThrough>
              <ClickTracking id="123">http://www.example.com/click</ClickTracking>
            </VideoClicks>
            <MediaFiles>
              <MediaFile delivery="progressive" apiFramework="VPAID" type="application/javascript" width="640" height="480"> https://googleads.github.io/googleads-ima-html5/vpaid/linear/VpaidVideoAd.js </MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>
```

The following example shows the tracking information.

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "1",
          "adParameters": "",
          "adProgramDateTime": "2023-07-31T16:53:40.577Z",
          "adSystem": "2.0",
          "adTitle": "1",
          "adVerifications": [],
          "companionAds": [],
          "creativeId": "00006",
          "creativeSequence": "1",
          "duration": "PT14.982S",
          "durationInSeconds": 14.982,
          "extensions": [],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": null,
          "startTime": "PT39.339S",
          "startTimeInSeconds": 39.339,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://myads.com/beaconing/event=impression"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698188",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            },
            {
              "beaconUrls": [
                "https://aws.amazon.com"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698188",
              "eventProgramDateTime": null,
              "eventType": "clickThrough",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            },
            {
              "beaconUrls": [
                "https://myads.com/beaconing/event=clicktracking"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698795",
              "eventProgramDateTime": null,
              "eventType": "clickTracking",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            }
          ],
          "vastAdId": ""
        }
      ],
      "availId": "2698188",
      "availProgramDateTime": "2023-07-31T16:53:40.577Z",
      "duration": "PT14.982S",
      "durationInSeconds": 14.982,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT39.339S",
      "startTimeInSeconds": 39.339
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQzOS4zMzlTXzIwMjMtMDctMzFUMTY6NTQ6MDQuODA1Mzk2NTI5Wl8x",
  "nonLinearAvails": []
}{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "2922274",
          "adParameters": "",
          "adProgramDateTime": "2023-08-14T19:49:53.998Z",
          "adSystem": "Innovid Ads",
          "adTitle": "VPAID",
          "adVerifications": [],
          "companionAds": [],
          "creativeId": "",
          "creativeSequence": "",
          "duration": "PT16.016S",
          "durationInSeconds": 16.016,
          "extensions": [],
          "mediaFiles": {
            "mediaFilesList": [
              {
                "apiFramework": "VPAID",
                "bitrate": 0,
                "codec": null,
                "delivery": "progressive",
                "height": 9,
                "id": "",
                "maintainAspectRatio": false,
                "maxBitrate": 0,
                "mediaFileUri": "http://my-ads.com/mobileapps/js/vpaid/1h41kg?cb=178344c0-8e67-281a-58ca-962e4987cd60&deviceid=&ivc=",
                "mediaType": "application/javascript",
                "minBitrate": 0,
                "scalable": false,
                "width": 16
              }
            ],
            "mezzanine": "http://my-ads.com/mobileapps/js/vpaid/1h41kg?cb=178344c0-8e67-281a-58ca-962e4987cd60&deviceid=&ivc="
          },
          "skipOffset": null,
          "startTime": "PT8M42.289S",
          "startTimeInSeconds": 522.289,
          "trackingEvents": [
            {
              "beaconUrls": [
                "about:blank"
              ],
              "duration": "PT16.016S",
              "durationInSeconds": 16.016,
              "eventId": "2922274",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT8M42.289S",
              "startTimeInSeconds": 522.289
            }
          ],
          "vastAdId": "1h41kg"
        }
      ],
      "availId": "2922274",
      "availProgramDateTime": "2023-08-14T19:49:53.998Z",
      "duration": "PT16.016S",
      "durationInSeconds": 16.016,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT8M42.289S",
      "startTimeInSeconds": 522.289
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQ4TTQyLjI4OVNfMjAyMy0wOC0xNFQxOTo1MDo0MS4zOTc5MjAzODVaXzE%3D",
  "nonLinearAvails": []
}
```

## Icons for Google Why This Ad (WTA)
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-google-wta"></a>

*AdChoices* is an industry standard that provides viewers with information about the ads they see, including how those ads were targeted to them.

![\[Google Why This Ad (WTA) logo. WTA informs viewers about the ads they see, including how those ads were targeted to them.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/google-wta.png)


The MediaTailor client-side tracking API supports icon metadata carried in the VAST extensions node of the VAST response. For more information about WTA in the VAST response, see [this sample VAST XML response](https://storage.googleapis.com/interactive-media-ads/ad-tags/ima_wta_sample_vast_3.xml).

**Note**  
MediaTailor currently supports VAST version 3 only.

```
<VAST>
    <Ad>  
    <InLine>  
       ...
      <Extensions>
        <Extension type="IconClickFallbackImages">
          <IconClickFallbackImages program="GoogleWhyThisAd">
            <IconClickFallbackImage width="400" height="150">
              <AltText>Alt icon fallback</AltText>
              <StaticResource creativeType="image/png"><![CDATA[https://storage.googleapis.com/interactive-media-ads/images/wta_dialog.png]]></StaticResource>
            </IconClickFallbackImage>
          </IconClickFallbackImages>
          <IconClickFallbackImages program="AdChoices">
            <IconClickFallbackImage width="400" height="150">
              <AltText>Alt icon fallback</AltText>
              <StaticResource creativeType="image/png"><![CDATA[https://storage.googleapis.com/interactive-media-ads/images/wta_dialog.png?size=1x]]></StaticResource>
            </IconClickFallbackImage>
            <IconClickFallbackImage width="800" height="300">
              <AltText>Alt icon fallback</AltText>
              <StaticResource creativeType="image/png"><![CDATA[https://storage.googleapis.com/interactive-media-ads/images/wta_dialog.png?size=2x]]></StaticResource>
            </IconClickFallbackImage>
          </IconClickFallbackImages>
        </Extension>
      </Extensions>
    </InLine>
  </Ad>
</VAST>
```

The following example shows the client-side tracking response in the `/avails/x/ads/y/extensions` list.

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "0",
          "adParameters": "",
          "adProgramDateTime": null,
          "adSystem": "GDFP",
          "adTitle": "Google Why This Ad VAST 3 Sample",
          "adVerifications": [],
          "companionAds": [],
          "creativeId": "7891011",
          "creativeSequence": "1",
          "duration": "PT10S",
          "durationInSeconds": 10,
          "extensions": [
            {
              "content": "<IconClickFallbackImages program=\"GoogleWhyThisAd\">      
                          <IconClickFallbackImage height=\"150\" width=\"400\">      
                          <AltText>Alt icon fallback</AltText>      
                          <StaticResource creativeType=\"image/png\"><![CDATA[https://storage.googleapis.com/interactive-media-ads/images/wta_dialog.png]]>
                          </StaticResource>     
                          </IconClickFallbackImage>    
                          </IconClickFallbackImages>     
                          <IconClickFallbackImages program=\"AdChoices\">     
                          <IconClickFallbackImage height=\"150\" width=\"400\">     
                          <AltText>Alt icon fallback</AltText>       
                          <StaticResource creativeType=\"image/png\"><![CDATA[https://storage.googleapis.com/interactive-media-ads/images/wta_dialog.png?size=1x]]>
                          </StaticResource>      
                          </IconClickFallbackImage>      
                          <IconClickFallbackImage height=\"300\" width=\"800\">       
                          <AltText>Alt icon fallback</AltText>       
                          <StaticResource creativeType=\"image/png\"><![CDATA[https://storage.googleapis.com/interactive-media-ads/images/wta_dialog.png?size=2x]]>
                          </StaticResource>      
                          </IconClickFallbackImage>     
                          </IconClickFallbackImages>",
              "type": "IconClickFallbackImages"
            }
          ],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": "00:00:03",
          "startTime": "PT0S",
          "startTimeInSeconds": 0,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://example.com/view"
              ],
              "duration": "PT10S",
              "durationInSeconds": 10,
              "eventId": "0",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT0S",
              "startTimeInSeconds": 0
            }
          ],
          "vastAdId": "123456"
        }
      ],
      "availId": "0",
      "availProgramDateTime": null,
      "duration": "PT10S",
      "durationInSeconds": 10,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT0S",
      "startTimeInSeconds": 0
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQxMFNfMjAyMy0wNy0wNlQyMDo0MToxNy45NDE4MDM0NDhaXzE%3D",
  "nonLinearAvails": []
}
```

# Client-side beaconing
<a name="ad-reporting-client-side-beaconing"></a>

With the client-side tracking `startTimeInSeconds` element, you can use MediaTailor to support beacons timing.

The following JSON response shows the main beacon types: impressions, start, quartiles, and completion.

**Note**  
The Interactive Advertising Bureau (IAB) Video Impression Measurement Guidelines state that an impression requires the ad content to load client-side and, at a minimum, begin time to render into the player. For more information, see [Digital Video Ad Serving Template (VAST)](https://www.iab.com/guidelines/vast/) on the IAB website.

```
{
  "avails": [
    {
      "ads": [
        {
          "adId": "8104385",
          "duration": "PT15.100000078S",
          "durationInSeconds": 15.1,
          "startTime": "PT17.817798612S",
          "startTimeInSeconds": 17.817,
          "trackingEvents": [
          {
              "beaconUrls": [
                "http://exampleadserver.com/tracking?event=impression"
              ],
              "duration": "PT15.100000078S",
              "durationInSeconds": 15.1,
              "eventId": "8104385",
              "eventType": "impression",
              "startTime": "PT17.817798612S",
              "startTimeInSeconds": 17.817
            },
            {
              "beaconUrls": [
                "http://exampleadserver.com/tracking?event=start"
              ],
              "duration": "PT0S",
              "durationInSeconds": 0.0,
              "eventId": "8104385",
              "eventType": "start",
              "startTime": "PT17.817798612S",
              "startTimeInSeconds": 17.817
            },
            {
              "beaconUrls": [
                "http://exampleadserver.com/tracking?event=firstQuartile"
              ],
              "duration": "PT0S",
              "durationInSeconds": 0.0,
              "eventId": "8104386",
              "eventType": "firstQuartile",
              "startTime": "PT21.592798631S",
              "startTimeInSeconds": 21.592
            },
             {
              "beaconUrls": [
                "http://exampleadserver.com/tracking?event=midpoint"
              ],
              "duration": "PT0S",
              "durationInSeconds": 0.0,
              "eventId": "8104387",
              "eventType": "midpoint",
              "startTime": "PT25.367798651S",
              "startTimeInSeconds": 25.367
            },
            {
              "beaconUrls": [
                "http://exampleadserver.com/tracking?event=thirdQuartile"
              ],
              "duration": "PT0S",
              "durationInSeconds": 0.0,
              "eventId": "8104388",
              "eventType": "thirdQuartile",
              "startTime": "PT29.14279867S",
              "startTimeInSeconds": 29.142
            },
            {
              "beaconUrls": [
                "http://exampleadserver.com/tracking?event=complete"
              ],
              "duration": "PT0S",
              "durationInSeconds": 0.0,
              "eventId": "8104390",
              "eventType": "complete",
              "startTime": "PT32.91779869S",
              "startTimeInSeconds": 32.917
            }
          ]
        }
      ],
      "availId": "8104385",
      "duration": "PT15.100000078S",
      "durationInSeconds": 15.1,
      "startTime": "PT17.817798612S",
      "startTimeInSeconds": 17.817
    }
  ]
}
```

# Hybrid mode with server-side ad beacons
<a name="ad-reporting-hybrid-mode"></a>

MediaTailor supports a hybrid mode for session tracking. In this mode, the service emits playback-related ad-tracking events, but makes the complete client-side tracking payload available for the session

To enable hybrid tracking using playback prefixes, from the player initialize a new MediaTailor playback session using a request in one of the following formats, according to your protocol:

**Example : HLS format**  

```
POST master.m3u8
    {
        "adsParams": {
           "deviceType": "ipad"
       },
       "reportingMode":"server"
    }
```

**Example : DASH format**  

```
POST manifest.mpd
    {
        "adsParams": {
           "deviceType": "ipad"
       },
       "reportingMode":"server"
    }
```

MediaTailor maintains the following tracking events in hybrid mode:
+ Impression
+ Start
+ First quartile
+ Midpoint
+ Third quartile
+ Complete
+ `breakStart` (vmap)
+ `breakEnd` (vmap)

# Client-side ad-tracking integrations
<a name="ad-reporting-client-side-ad-tracking-integrations"></a>

This section describes integrations between MediaTailor and various client-side ad-tracking servers.

**Topics**
+ [Open Measurement SDK](#ad-reporting-client-side-ad-tracking-integrations-open-measurement-sdk)
+ [Datazoom free player SDKs](#ad-reporting-client-side-ad-tracking-integrations-dz)
+ [Roku Advertising Framework (RAF)](#ad-reporting-client-side-ad-tracking-integrations-raf)
+ [TheoPlayer](#ad-reporting-client-side-ad-tracking-integrations-theoplayer)
+ [MediaTailor SDK](#ad-reporting-client-side-ad-tracking-integrations-mediatailor-sdk)

## Open Measurement SDK
<a name="ad-reporting-client-side-ad-tracking-integrations-open-measurement-sdk"></a>

The Interactive Advertising Bureau (IAB) Open Measurement SDK (OM SDK) facilitates third-party viewability and verification measurement for ads served to web-video and native-app environments.

For older VAST version 3 documents, verification code should be loaded with the Extension node, with extension type `AdVerifications`. The root of the extension node is an `AdVerifications` node with the same schema as the VAST 4.1 element.

To facilitate easier adoption of the OM SDK, MediaTailor has partnered with Datazoom to provide free player SDKs that are configured and verified for Open Measurement. For more information, see [Datazoom free player SDKs](#ad-reporting-client-side-ad-tracking-integrations-dz).

**Note**  
MediaTailor currently supports VAST version 3 only.

**Example : Verification node in VAST 3, prior to Version 4.1**  

```
...
<Extensions>
    <Extension type="AdVerifications">
        <AdVerifications>
            <Verification vendor="company.com-omid">
                <JavaScriptResource apiFramework="omid" browserOptional="true">
                    <![CDATA[https://verification.com/omid_verification.js]]>
                </JavaScriptResource>
                <TrackingEvents>
                    <Tracking event="verificationNotExecuted">
                        <![CDATA[https://verification.com/trackingurl]]>
                    </Tracking>
                </TrackingEvents>
                <VerificationParameters>
                    <![CDATA[verification params key/value pairs]]>
                </VerificationParameters>
            </Verification>
        </AdVerifications>
    </Extension>
</Extensions>
```

MediaTailor extracts the `AdVerifications` data from the `<Extensions>` node and places it into the `adVerifications` array in the client-side tracking response.

**Example : adVerifications array in client-side tracking response**  

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "3062770",
          "adParameters": "",
          "adProgramDateTime": "2023-08-23T16:25:40.914Z",
          "adSystem": "2.0",
          "adTitle": "AD-polarbear-15",
          "adVerifications": [
            {
              "executableResource": [],
              "javaScriptResource": [
                {
                  "apiFramework": "omid",
                  "browserOptional": "true",
                  "uri": "https://verification.com/omid_verification.js"
                }
              ],
              "trackingEvents": [
                {
                  "event": "verificationNotExecuted",
                  "uri": "https://verification.com/trackingurl"
                }
              ],
              "vendor": "company.com-omid",
              "verificationParameters": "verification params key value pairs"
            }
          ],
          "companionAds": [],
          "creativeId": "00006",
          "creativeSequence": "1",
          "duration": "PT14.982S",
          "durationInSeconds": 14.982,
          "extensions": [
            {
              "content": "<AdVerifications>\n\t\t\t\t\t\t<Verification vendor=\"company.com-omid\">\n\t\t\t\t\t\t\t<JavaScriptResource apiFramework=\"omid\" browserOptional=\"true\"><![CDATA[https://verification.com/omid_verification.js;]]></JavaScriptResource>\n\t\t\t\t\t\t\t<TrackingEvents>\n\t\t\t\t\t\t\t\t<Tracking event=\"verificationNotExecuted\"><![CDATA[;https://verification.com/trackingurl;]]></Tracking>\n\t\t\t\t\t\t\t</TrackingEvents>\n\t\t\t\t\t\t\t<VerificationParameters><![CDATA[verification params key/value pairs;]]></VerificationParameters>\n\t\t\t\t\t\t</Verification>\n\t\t\t\t\t</AdVerifications>",
              "type": "AdVerifications"
            }
          ],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": null,
          "startTime": "PT10.11S",
          "startTimeInSeconds": 10.11,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://n8ljfs0h09.execute-api.us-west-2.amazonaws.com/v1/impression"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "3062770",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT10.11S",
              "startTimeInSeconds": 10.11
            }
          ],
          "vastAdId": ""
        }
      ],
      "availId": "3062770",
      "availProgramDateTime": "2023-08-23T16:25:40.914Z",
      "duration": "PT14.982S",
      "durationInSeconds": 14.982,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT10.11S",
      "startTimeInSeconds": 10.11
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQxMC4xMVNfMjAyMy0wOC0yM1QxNjoyNjoyNC4yNDYxMDIxOTBaXzE%3D",
  "nonLinearAvails": []
}
```

**Note**  
Engage with the IAB Tech Lab to ensure that applications are certified annually to ensure compliance.

For more information about the OM SDK, see [Open Measurement SDK](https://iabtechlab.com/standards/open-measurement-sdk/) on the IAB Tech Lab website.

## Datazoom free player SDKs
<a name="ad-reporting-client-side-ad-tracking-integrations-dz"></a>

To facilitate easier adoption of the player SDKs, MediaTailor has partnered with Datazoom to provide free player SDKs that are configured and tested with the [Client-side AWS Elemental MediaTailor integration with Google Ad Manager](gam-integration-pal.md) and the IAB Tech [Open Measurement SDK](#ad-reporting-client-side-ad-tracking-integrations-open-measurement-sdk).

The Datazoom player SDK supports these features:
+ Live and VOD playlists
+ DASH and HLS specifications
+ Player vendor support for Bitmovin, exoplayer, Android media player, Apple AVPlayer, Brightcove, Chromecast Receiver, Dash.js, hls.js, JWPlayer, Shaka player, THEO player, Video.js, Roku and more
+ IAB Tech Lab Open Measurement certification, where available on selected devices
+ Click-through event handling
+ Ad-event dispatchers, such as ad count down timers, ad overlay and non-linear events, ad-break start, ad-break end
+ Client-side ad beaconing
+ Google Programmatic Access Library (PAL) SDK, as an optional configuration setting

Datazoom also offers a paid analytics and telemetry service that the player SDKs support. Customers can opt into and control player SDK telemetry from the Datazoom management console. To access the Datazoom player SDKs and to learn more about the value-added telemetry and analytics service, use the contact information on the [Datazoom site](https://www.datazoom.io/partner-aws). 

## Roku Advertising Framework (RAF)
<a name="ad-reporting-client-side-ad-tracking-integrations-raf"></a>

The Roku Ad Framework (RAF) maintains a consistent ad experience across the Roku platform. All channels, including video advertisements, must meet Roku's certification requirements for RAF. Notably, the app must always use client-side event firing through RAF. MediaTailor, as a server-side ad insertion (SSAI) provider, supports client-side event firing. The RAFX SSAI Adapters provide interfaces to both SSAI manifest servers, or stitchers, and RAF. These interfaces include:
+ Parsing the `masterURL` response and extracting `playURL`, `AdURL`, and ad metadata.
+ Transforming MediaTailor SSAI ad metadata into RAF-usable ad metadata, and configuring RAF for playback.
+ Observing stream events and timed metadata.
+ Matching the stream events, ad metadata, and firing-event pixels on time.
+ Pinging/polling the `AdURL`, as required by the MediaTailor SSAI manifest server, then parsing and re-configuring RAF.

For more information about SSAI adapters for RAF, see [Implementing Server-Side Ad Insertion Using Roku Adapters](https://developer.roku.com/docs/developer-program/advertising/ssai-adapters.md) on the Roku website.

## TheoPlayer
<a name="ad-reporting-client-side-ad-tracking-integrations-theoplayer"></a>

TheoPlayer integration with MediaTailor does the following:
+ Provides functionality to support MediaTailor client-side event tracking for HLS and DASH for both VOD and live workflows.
+ Supports sending tracking beacons only for linear ads.
+ Disables seeking during an ad. However, no logic is in place for playing an ad when the user seeks past the ad break.

For more information about SSAI in TheoPlayer, and to review the web, Android, iOS, and tvOS SDKs for MediaTailor, see [MediaTailor](https://docs.theoplayer.com/how-to-guides/01-ads/12-mediatailor.md) on the TheoPlayer website.

## MediaTailor SDK
<a name="ad-reporting-client-side-ad-tracking-integrations-mediatailor-sdk"></a>

AWS Elemental maintains a JavaScript-based software-development kit (SDK). AWS Elemental provides the SDK as-is, with no implied warranty. Use the SDK as a reference demonstration to streamline your onboarding to using MediaTailor. The SDK shows how to interact with the MediaTailor client-side tracking API. The SDK implements client-side ad tracking and reporting for HTML5-based players. The SDK initializes a MediaTailor client-side reporting session, then periodically requests ad-tracking information. During playback, the SDK emits ad tracking events when new ad events are detected.

The MediaTailor SDK supports these features:
+ Live and VOD playlists
+ DASH and HLS specifications
+ Click-through event handling
+ Ad-event dispatchers
+ Custom event hooks
+ Client-side ad beaconing. For more information about sending ad beacons, see [Client-side beaconing](ad-reporting-client-side-beaconing.md).

**Note**  
Submit an AWS Support ticket to receive a sample JavaScript SDK for MediaTailor. You'll receive a download link for the package and its files.

## Paging through ad beacons with GetTracking
<a name="gettracking"></a>

Use the `GetTracking` endpoint to narrow the number of ad returned to a player. For instance, if a manifest window is wide, spanning a lot of time, the number of returned ad beacons can impact player performance. 

`GetTracking` returns a `NextToken` value you can use to narrow the number of returned beacons by paging through the list of returned beacons. You can cycle through the `NextToken` values to find the desired value of an ad beacon's `StartTimeInSeconds` field. 
+ On the first call to `GetTracking`, all possible ads falling in the manifest window are returned, including a `NextToken` and value of each. 
+ If a `GetTracking` request does *not* include a `NextToken`, all ads in the manifest window are returned.
+ If a `GetTracking` request contains a `NextToken` but there are no new beacons to return, MediaTailor returns the same value for `NextToken` that you sent on the original request.
+ When there are no more beacons corresponding to an ad, `GetTracking` removes the ad from its response.
+ Tokens from `GetTracking` expire after 24 hours. If a `NextToken` value is greater than 24 hours old, the next call to `GetTracking` returns a null-value `NextToken`.

### Generalized calling sequence of GetTracking from player
<a name="gettracking.generalsequence"></a>

From the client player, a `GetTracking` request is a POST with a request body that contains the `NextToken` and ads and beacons related to the token.

```
https://YouMediaTailorUrl/v1/tracking
{

     "NextToken": "value"
     .
     .
     .
}
```

The general sequence for using `GetTracking` with `NextToken` is as follows:

1. Make the first call to `GetTracking`.

   All ads and beacons and the first `NextToken` for subsequent calls are returned. 

1. If the value of `NextToken` is null, MediaTailor returns all ad beacons.

1. If the `NextToken` is expired, MediaTailor returns an HTTP return code 400 error message.

   Make a fresh call to `GetTracking` to retrieve valid `NextToken`s.

1. Scan the entire response to find the `StartTimeInSeconds` of an ad beacon that is in the desired range.

1. Make a new call to `GetTracking` with the value of `NextToken` associated with the desired `StartTimeInSeconds`. 

1. If necessary, cycle again through the returned ads until you find the exact ones you want to play.

#### Extended example
<a name="gettracking.extendedexample"></a>

This example shows how to use `GetTracking`'s `NextToken` to constrain the number of ad beacons returned to a player.

MediaTailor receives a `GetTracking` request. The response contains an ad with ID 9935407 and two beacons with `StartTimeInSeconds` values 52.286 and 48.332 seconds. 

MediaTailor sends the JSON response with `NextToken` as follows:

```
  {
  "NextToken": JF57ITe48t1441mv7TmLKuZLroxDzfIslp6BiSNL1IJmzPVMDN0lqrBYycgMbKEb
  "avails": [
    {
      "ads": [
        {
          "adId": "9935407",
          "adVerifications": [],
          "companionAds": [],
          "creativeId": "",
          "creativeSequence": "",
          "duration": "PT15S",
          "durationInSeconds": 15,
          "extensions": [],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "startTime": "PT30S",
          "StartTimeInSeconds": 45,
          "trackingEvents": [
            {
              "beaconUrls": [
                "http://adserver.com/tracking?event=Impression "
              ],
              "duration": "PT0S",
              "durationInSeconds": 0,
              "eventId": "9935414",
              "eventType": "secondQuartile",
              "startTime": "PT52.286S",
              "StartTimeInSeconds": 52.286
            },
            {
              "beaconUrls": [
                "http://adserver.com/tracking?event=firstQuartile"
              ],
              "duration": "PT0S",
              "durationInSeconds": 0,
              "eventId": "9935412",
              "eventType": "firstQuartile",
              "startTime": "PT48.332S",
              "StartTimeInSeconds": 48.332
            }
          ],
          "vastAdId": ""
        }
      ],
      "startTime": "PT46.47S",
      "StartTimeInSeconds": 46.47
    }
  ]
}
```

On the next `GetTracking` request, MediaTailor responds with the `NextToken` value,: JF57ITe48t1441mv7TmLKuZLroxDzfIslp6BiSNL1IJmzPVMDN0lqrBYycgMbKEb.

MediaTailor responds with ads and beacons that match the `StartTimeInSeconds` that are set in the `NextToken` of the previous call.

Assume that now the response includes another ad with ID 9235407 in addition to the previous ad with ID 9935407. The beacons of ad ID 9235407 have `StartTimeInSeconds`s 132.41 and 70.339.

MediaTailor iterates over all the beacons in the session to select the ones with `StartTimeInSeconds` greater than 52.286 seconds, which are beacon 3 and beacon 4 from the ad with ID 9235407:

```
{
  "NextToken": ZkfknvbfsdgfbsDFRdffg12EdffecFRvhjyjfhdfhnjtsg5SDGN
  "avails": [
    {
      "ads": [
        {
          "adId": "9235407",
          "adVerifications": [],
          "companionAds": [],
          "creativeId": "",
          "creativeSequence": "",
          "duration": "PT15.816S",
          "durationInSeconds": 19.716,
          "extensions": [],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "startTime": "PT2M0S",
          "StartTimeInSeconds": 120.0,
          "trackingEvents": [
            {
              "beaconUrls": [
                "http://adserver.com/tracking?event=complete"
              ],
              "duration": "PT0S",
              "durationInSeconds": 0,
              "eventId": "8935414",
              "eventType": "firstQuartile",
              "startTime": "PT1M10.330S",
              "StartTimeInSeconds": 70.339
            },
            {
              "beaconUrls": [
                "http://adserver.com/tracking?event=thirdQuartile"
              ],
              "duration": "PT0S",
              "durationInSeconds": 0,
              "eventId": "8935412",
              "eventType": "secondQuartile",
              "startTime": "PT2M12.41S",
              "StartTimeInSeconds": 132.41
            }
          ],
          "vastAdId": ""
        },   
      ],
      "startTime": "PT36.47S",
      "StartTimeInSeconds": 36.47
    }
  ]
}
```

# Overlay ads
<a name="overlay-ads"></a>

For live-streaming workflows where you want to increase monetization without interrupting the viewing experience with mid-roll ads, you can leverage your current AWS Elemental MediaTailor integration to guide an advertising format that is rendered client-side. This type of advertising is known as *overlay ads*. Overlay ads are non-linear video ads that appear in the form of 'L-band ads,' 'non-linear video ads,' 'picture-in-picture ads,' 'motion overlays', 'in-content advertising', or 'frame ads.'

MediaTailor detects a SCTE-35 marker with segmentation type `id=0x38` as an in-band signal for an overlay ad-insertion opportunity. The SCTE-35 marker causes MediaTailor to send a request to the Ad Decision Server (ADS), which then responds with a non-linear ad payload in the VAST response. MediaTailor parses the VAST response in order to support overlay ad insertion. MediaTailor does not perform any stitching of linear ads, but rather signals to the player that there's a non-linear overlay ad available to play. This signaling allows the player to fetch and correlate the non-linear ads to play from the client-side tracking endpoint. The player then handles the display, reporting, and other tasks related to those ads. For example, the player's developer can use a device SDK from a vendor that supports overlay-ad formats. For more information about client-side tracking integrations, see [Client-side ad-tracking integrations](ad-reporting-client-side-ad-tracking-integrations.md).

![\[The image depicts a timeline of various ad types displayed alongside a content video. Linear ads play before and after the content video. The ad before the content video is called a pre-roll ad. The ad after the content video is called a post-roll ad. A non-linear ad overlaps a portion of the content video itself. The non-linear ad is called an overlay ad.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/client-side-overlays.png)


**Topics**
+ [Prerequisites for using overlay ads with MediaTailor](overlay-ads-prerequisites.md)
+ [Getting started using overlay ads with MediaTailor](overlay-ads-getting-started.md)
+ [Logging and metrics for overlay ads in MediaTailor](overlay-ads-logging-and-metrics.md)
+ [Billing for overlay ads in MediaTailor](overlay-ads-billing.md)

# Prerequisites for using overlay ads with MediaTailor
<a name="overlay-ads-prerequisites"></a>

The following prerequisites apply when using overlay ads with MediaTailor:
+ The workflow must be live, not video on demand (VOD).
+ The Ad Decision Server (ADS) response must be configured to return only non-linear ads in the VAST response. MediaTailor ignores any linear ads for the purposes of ad stitching.
+ The manifest must use a SCTE-35 time signal message with segmentation type `id=0x38` to invoke the overlay-ad feature.
+ The streaming provider must have control of the client-device application and be integrated with the MediaTailor client-side tracking API.

# Getting started using overlay ads with MediaTailor
<a name="overlay-ads-getting-started"></a>

This section explains how to get started using the overlay-ads feature of MediaTailor. You'll set up SCTE-35 signaling, configure Ad Decision Server (ADS) responses, and set up session-level control.

**Topics**
+ [Enabling overlay ads](overlay-ads-getting-started-enabling.md)
+ [Tracking overlay ads with client-side metadata](overlay-ads-client-side-tracking-metadata.md)

# Enabling overlay ads
<a name="overlay-ads-getting-started-enabling"></a>

MediaTailor support for overlay ads is enabled by default. A specific SCTE-35 ad-marker type in the manifest triggers the insertion of an overlay ad. Because some players might not support client-side rendering of overlay ads, you can disable the feature at the session level.

**To disable overlay-ad support using HLS or DASH playback prefixes:**
+ From the player, initialize a new MediaTailor playback session using a request in one of the following formats, according to your protocol:
  + Example: HLS format

    ```
    GET mediatailorURL/v1/master/hashed-account-id/origin-id/asset-id?aws.overlayAvails=off
    ```
  + Example: DASH format

    ```
    GET mediatailorURL/v1/master/hashed-account-id/origin-id/asset-id?aws.overlayAvails=off
    ```

**To disable overlay-ad support using the session-initialization prefix:**
+ On the player, construct a JSON message body for the session initialization request to MediaTailor:
  + To disable ad-overlay support, add an `overlays` object as a top-level key with a value of `off`. The default `overlays` value is `on`.
  + (Optional) Provide any parameters that MediaTailor then passes to the ADS inside an `adsParams` object. These parameters correspond to `[player_params.param]` settings in the ADS template URL of the MediaTailor configuration.

**Example : HLS**  

```
POST master.m3u8
    {
       "adsParams": {
           "deviceType": "ipad"
       },
       "overlayAvails": "off"
    }
```

**Example : DASH**  

```
POST manifest.mpd
    {
        "adsParams": {
           "deviceType": "androidmobile"
       },
       "overlayAvails": "off"
    }
```

# Manifest signaling
<a name="overlay-ads-manifest-signaling"></a>

MediaTailor trigger overlay-ads support when it sees a specific SCTE-35 marker in the manifest. The required signal is a splice command type 6, or time signal, that is a Provider Overlay Advertisement Start signal. This signal has a segmentation type id of `0x38`

The following example shows the `0x38` SCTE-35 marker in a JSON object.

```
{
  "tableId": 252,
  "selectionSyntaxIndicator": false,
  "privateIndicator": false,
  "sectionLength": 53,
  "protocolVersion": 0,
  "encryptedPacket": false,
  "encryptedAlgorithm": 0,
  "ptsAdjustment": 0,
  "cwIndex": 0,
  "tier": 4095,
  "spliceCommandLength": 5,
  "spliceCommandType": 6,
  "spliceCommand": {
    "specified": true,
    "pts": 1800392
  },
  "descriptorLoopLength": 31,
  "descriptors": [
    {
      "spliceDescriptorTag": 2,
      "descriptorLength": 29,
      "indentifier": "CUEI",
      "segmentationEventId": 158389361,
      "segmentationEventCancelIndicator": false,
      "programSegmentationFlag": true,
      "segmentationDurationFlag": true,
      "deliveryNotRestrictedFlag": false,
      "webDeliveryAllowedFlag": true,
      "noRegionalBlackoutFlag": true,
      "archiveAllowedFlag": true,
      "deviceResctrictions": 3,
      "segmentationDuration": 1350000,
      "segmentationUpidType": 9,
      "segmentationUpidLength": 7,
      "segmentationUpid": {
        "0": 111,
        "1": 118,
        "2": 101,
        "3": 114,
        "4": 108,
        "5": 97,
        "6": 121
      },
      "segmentationTypeId": 56,
      "segmentNum": 1,
      "segmentsExpected": 0
    }
  ],
  "crc": 2510422713
}
```

The following example shows the SCTE-35 signal represented as a binary (base 32/hexadecimal) value:

```
0xfc303500000000000000fff00506fe001b78c8001f021d435545490970d4717fdf00000dbba009076f7665726c6179380100000084226c4f
```

The following examples shows the SCTE-35 marker in both HLS and DASH manifests.

**Example : HLS manifest**  

```
#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:7
#EXT-X-MEDIA-SEQUENCE:419
#EXT-X-DISCONTINUITY-SEQUENCE:3
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:09.231Z
#EXTINF:6.02,
https://aws.cloudfront.net/media/asset1/index1_00007.ts
#EXT-X-DISCONTINUITY
#EXT-X-KEY:METHOD=NONE
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:15.251Z
#EXTINF:6.0,
https://aws.cloudfront.net/media/asset1/index1_00001.ts
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:21.251Z
#EXTINF:4.0,
https://aws.cloudfront.net/media/asset1/index1_00002.ts
#EXT-X-DISCONTINUITY
#EXT-X-DATERANGE:ID="1692073825251-30-1",START-DATE="2023-08-15T04:30:25.251Z",DURATION=10.0,PLANNED-DURATION=10.0,SCTE35-OUT=0xfc303500000000000000fff00506fe001b78c8001f021d435545490970d4717fdf00000dbba009076f7665726c6179380100000084226c4f
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:25.251Z
#EXTINF:2.0,
https://aws.cloudfront.net/media/asset1/index1_00003.ts
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:27.251Z
#EXTINF:6.0,
https://aws.cloudfront.net/media/asset1/index1_00004.ts
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:33.251Z
#EXTINF:2.0,
https://aws.cloudfront.net/media/asset1/index1_00005.ts
#EXT-X-DISCONTINUITY
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:35.251Z
#EXTINF:4.0,
https://aws.cloudfront.net/media/asset1/index1_00006.ts
#EXT-X-PROGRAM-DATE-TIME:2023-08-15T04:30:39.251Z
#EXTINF:6.02,
https://aws.cloudfront.net/media/asset1/index1_00007.ts
```

**Example : DASH manifest**  

```
<?xml version="1.0"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" xmlns:scte35="urn:scte:scte35:2013:xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" availabilityStartTime="2023-08-15T16:34:05.911Z" minBufferTime="PT30S" minimumUpdatePeriod="PT2S" profiles="urn:mpeg:dash:profile:isoff-live:2011" publishTime="2023-08-15T16:34:17.950Z" suggestedPresentationDelay="PT20S" timeShiftBufferDepth="PT1M30S" type="dynamic" xsi:schemaLocation="urn:mpeg:dash:schema:mpd:2011 http://standards.iso.org/ittf/PubliclyAvailableStandards/MPEG-DASH_schema_files/DASH-MPD.xsd">
  <Period xmlns="urn:mpeg:dash:schema:mpd:2011" id="1692117245944_1" start="PT0.033S">
    <BaseURL>https://aws.cloudfront.net/out/v1/abc/123/def/</BaseURL>
    <EventStream schemeIdUri="urn:scte:scte35:2013:xml" timescale="90000">
      <Event duration="900000">
        <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="0" tier="4095">
          <scte35:TimeSignal>
            <scte35:SpliceTime ptsTime="0"/>
          </scte35:TimeSignal>
          <scte35:SegmentationDescriptor segmentNum="0" segmentationDuration="900000" segmentationEventCancelIndicator="false" segmentationEventId="1" segmentationTypeId="56" segmentsExpected="0" subSegmentNum="0" subSegmentsExpected="0">
            <scte35:SegmentationUpid segmentationUpidFormat="hexBinary" segmentationUpidType="14">63736f7665726c6179</scte35:SegmentationUpid>
          </scte35:SegmentationDescriptor>
        </scte35:SpliceInfoSection>
      </Event>
    </EventStream>
    <AdaptationSet bitstreamSwitching="true" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1">
      <Representation bandwidth="3000000" codecs="avc1.4D4028" frameRate="30/1" height="1080" id="1" width="1920">
        <SegmentTemplate initialization="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_video_1_0_init.mp4" media="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_video_1_0_$Number$.mp4" presentationTimeOffset="0" startNumber="1" timescale="30000">
          <SegmentTimeline>
            <S d="60000" r="6" t="1000"/>
            <S d="30000" t="421000"/>
          </SegmentTimeline>
        </SegmentTemplate>
      </Representation>
      <Representation bandwidth="2499968" codecs="avc1.4D4028" frameRate="30/1" height="1080" id="2" width="1920">
        <SegmentTemplate initialization="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_video_2_0_init.mp4" media="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_video_2_0_$Number$.mp4" presentationTimeOffset="0" startNumber="1" timescale="30000">
          <SegmentTimeline>
            <S d="60000" r="6" t="1000"/>
            <S d="30000" t="421000"/>
          </SegmentTimeline>
        </SegmentTemplate>
      </Representation>
      <Representation bandwidth="2200000" codecs="avc1.4D401F" frameRate="30/1" height="720" id="3" width="1280">
        <SegmentTemplate initialization="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_video_3_0_init.mp4" media="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_video_3_0_$Number$.mp4" presentationTimeOffset="0" startNumber="1" timescale="30000">
          <SegmentTimeline>
            <S d="60000" r="6" t="1000"/>
            <S d="30000" t="421000"/>
          </SegmentTimeline>
        </SegmentTemplate>
      </Representation>
    </AdaptationSet>
    <AdaptationSet lang="eng" mimeType="audio/mp4" segmentAlignment="0">
      <Label>Alternate Audio</Label>
      <Representation audioSamplingRate="48000" bandwidth="128000" codecs="mp4a.40.2" id="9">
        <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
        <SegmentTemplate initialization="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_audio_9_0_init.mp4" media="../cf684d31ec9e451ca98d2349989f6c0a/855c733eed20493ab3cc1100750bcf0b/index_audio_9_0_$Number$.mp4" presentationTimeOffset="0" startNumber="1" timescale="48000">
          <SegmentTimeline>
            <S d="98304" t="0"/>
            <S d="96256" t="98304"/>
            <S d="95232" t="194560"/>
            <S d="96256" r="2" t="289792"/>
            <S d="95232" t="578560"/>
            <S d="46080" t="673792"/>
          </SegmentTimeline>
        </SegmentTemplate>
      </Representation>
    </AdaptationSet>
  </Period>
</MPD>
```

# Ad Decision Server (ADS) response
<a name="overlay-ads-ads-response"></a>

The ADS response must contain one valid tracking event. At minimum, the tracking event can be an `Impression` tracking event. The tracking event should contain at least one `NonLinear` ad. This ad is the overlay ad, taking the form of a static, HTML, or iFrame resource.

```
<vmap AdBreak breaktype="linear" breakId="csoverlay"
```

If the VAST response is a VMAP with `breakType` of `nonlinear`, the avail metadata is inside the `nonLinearAvails` root object. If the VAST response is a VMAP with a `breakType` of `linear`, or is a plain VAST response without VMAP, the avail metadata is inside the `avails` root object.

The following VAST response is a wrapped VMAP response with a `breakType` value of `linear`.

In addition to the wrapped VMAP response, MediaTailor also supports a wrapped VMAP response with a `breakType` value of `nonlinear`, and a plain VAST response.

```
<?xml version="1.0" encoding="utf-8"?>
<vmap:VMAP xmlns:vmap="http://www.iab.net/vmap-1.0" version="1.0">
  <vmap:AdBreak breakType="linear" breakId="csoverlay">
    <vmap:AdSource allowMultipleAds="true" followRedirects="true" id="1">
      <vmap:VASTAdData>
        <VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="3.0" xsi:noNamespaceSchemaLocation="vast.xsd">
          <Ad sequence="1">
            <InLine>
              <AdSystem>2.0</AdSystem>
              <AdTitle>2</AdTitle>
              <Impression><![CDATA[https://adserver.com/beacon=impression]]></Impression>
              <Creatives>
                <Creative>
                  <NonLinearAds>
                    <NonLinear width="640" height="360" id="18">
                      <StaticResource creativeType="text/js_ref"><![CDATA[https://client-side-ads.com/tags/static/ctv-generic/overlay001.json?iv_geo_country%3DUS%26]]></StaticResource>
                    </NonLinear>
                  </NonLinearAds>
                </Creative>
              </Creatives>
            </InLine>
          </Ad>
        </VAST>
      </vmap:VASTAdData>
    </vmap:AdSource>
    <vmap:TrackingEvents>
      <vmap:Tracking event="breakStart"><![CDATA[https://adserver.com/beacon=breakstartimpression]]></vmap:Tracking>
      <vmap:Tracking event="breakEnd"><![CDATA[https://adserver.com/beacon=breakendimpression]]></vmap:Tracking>
    </vmap:TrackingEvents>
  </vmap:AdBreak>
</vmap:VMAP>
```

**Example 1: DASH manifest source to MediaTailor**  

```
<?xml version="1.0" encoding="utf-8"?>
<MPD xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:mpeg:dash:schema:mpd:2011" xmlns:scte35="urn:scte:scte35:2013:xml" xsi:schemaLocation="urn:mpeg:dash:schema:mpd:2011 http://standards.iso.org/ittf/PubliclyAvailableStandards/MPEG-DASH_schema_files/DASH-MPD.xsd" id="201" type="dynamic" publishTime="2022-11-07T19:59:05+00:00" minimumUpdatePeriod="PT2S" availabilityStartTime="2022-11-07T06:57:11.250000+00:00" minBufferTime="PT10S" suggestedPresentationDelay="PT20.000S" timeShiftBufferDepth="PT58.999S" profiles="urn:mpeg:dash:profile:isoff-live:2011">
  <Period start="PT46827.601S" id="0" duration="PT88.321S">
  ...
  </Period>
  <Period start="PT46915.922S" id="45" duration="PT6.006S">
    <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2014:xml+bin">
    <Event duration="540000" id="144">
        <scte35:Signal>
            <scte35:Binary>SCTE35-binary</scte35:Binary>
        </scte35:Signal>
    </Event>
    </EventStream>
    ... 
  </Period>
  <Period start="PT46921.928S" id="49"> 
  ...
  </Period>
</MPD>
```

**Example 2: MediaTailor personalized DASH manifest containing an ad ID decoration**  

```
<?xml version="1.0" encoding="utf-8"?>
<MPD xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:mpeg:dash:schema:mpd:2011" xmlns:scte35="urn:scte:scte35:2013:xml" xsi:schemaLocation="urn:mpeg:dash:schema:mpd:2011 http://standards.iso.org/ittf/PubliclyAvailableStandards/MPEG-DASH_schema_files/DASH-MPD.xsd" id="201" type="dynamic" publishTime="2022-11-07T19:59:05+00:00" minimumUpdatePeriod="PT2S" availabilityStartTime="2022-11-07T06:57:11.250000+00:00" minBufferTime="PT10S" suggestedPresentationDelay="PT20.000S" timeShiftBufferDepth="PT58.999S" profiles="urn:mpeg:dash:profile:isoff-live:2011">
  <Period start="PT46827.601S" id="0" duration="PT88.321S">
  ...
  </Period>
  <Period start="PT46915.922S" id="45" duration="PT6.006S">
  <EventStream schemeIdUri="urn:sva:advertising-wg:ad-id-signaling" timescale="90000">
    <Event presentationTime="13500000" duration="1351350">
    <![CDATA[{"version": 1,"identifiers": [{"scheme": "urn:smpte:ul:060E2B34.01040101.01200900.00000000","value": "adId","ad_position": "adId", "ad_type":"overlay","creative_id": "creativeId","tracking_uri": "trackingUri"}]}]]></Event>
  </EventStream>
  ...
  </Period>
  <Period start="PT46921.928S" id="49"> 
  ...
  </Period>
</MPD>
```

# Tracking overlay ads with client-side metadata
<a name="overlay-ads-client-side-tracking-metadata"></a>

MediaTailor places the overlay ads in the `nonLinearAdsList` of the avail. The MediaTailor client-side tracking API has two root objects, called `avails` and `nonLinearAvails`. If the VAST response is a VMAP with `breakType` of `nonlinear`, the avail metadata is inside the `nonLinearAvails` root object. If the VAST response is a VMAP with a `breakType` of `linear`, or is a plain VAST response without VMAP, the avail metadata is inside the `avails` root object.

For more information about client-side tracking, see [Client-side ad tracking](ad-reporting-client-side.md).

The following example shows a plain VAST response or VMAP response with a `breakType` value of `linear`.

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [
        {
          "beaconUrls": [
            "https://adserver.com/beacon=breakstartimpression"
          ],
          "eventType": "breakStart"
        },
        {
          "beaconUrls": [
            "https://adserver.com/beacon=breakendimpression"
          ],
          "eventType": "breakEnd"
        }
      ],
      "adMarkerDuration": null,
      "ads": [],
      "availId": "828",
      "availProgramDateTime": null,
      "duration": "PT0S",
      "durationInSeconds": 0,
      "meta": null,
      "nonLinearAdsList": [
        {
          "extensions": null,
          "nonLinearAdList": [
            {
              "adId": "",
              "adParameters": null,
              "adSystem": "2.0",
              "adTitle": "2",
              "apiFramework": null,
              "clickThrough": null,
              "clickTracking": null,
              "clickTrackingId": null,
              "creativeAdId": "",
              "creativeId": "18",
              "creativeSequence": "",
              "duration": null,
              "durationInSeconds": 0,
              "expandedHeight": null,
              "expandedWidth": null,
              "height": "360",
              "htmlResource": null,
              "iFrameResource": null,
              "maintainAspectRatio": false,
              "minSuggestedDuration": null,
              "scalable": false,
              "staticResource": "https://client-side-ads.com/tags/static/ctv-generic/overlay001.json?iv_geo_country%3DUS%26",
              "staticResourceCreativeType": "text/js_ref",
              "width": "640"
            }
          ],
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://adserver.com/beacon=impression"
              ],
              "duration": null,
              "durationInSeconds": 0,
              "eventId": null,
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": null,
              "startTimeInSeconds": 0
            }
          ]
        }
      ],
      "startTime": "PT1M46.08S",
      "startTimeInSeconds": 106.08
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": null,
  "nonLinearAvails": []
}
```

The following example shows a plain VMAP response with a `breakType` value of `nonlinear`.

```
{
  "avails": [],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": null,
  "nonLinearAvails": [
    {
      "adBreakTrackingEvents": [
        {
          "beaconUrls": [
            "https://adserver.com/beacon=breakstartimpression"
          ],
          "eventType": "breakStart"
        },
        {
          "beaconUrls": [
            "https://adserver.com/beacon=breakendimpression"
          ],
          "eventType": "breakEnd"
        }
      ],
      "adMarkerDuration": null,
      "ads": [],
      "availId": "828",
      "availProgramDateTime": null,
      "duration": "PT0S",
      "durationInSeconds": 0,
      "meta": null,
      "nonLinearAdsList": [
        {
          "extensions": null,
          "nonLinearAdList": [
            {
              "adId": "",
              "adParameters": null,
              "adSystem": "2.0",
              "adTitle": "2",
              "apiFramework": null,
              "clickThrough": null,
              "clickTracking": null,
              "clickTrackingId": null,
              "creativeAdId": "",
              "creativeId": "18",
              "creativeSequence": "",
              "duration": null,
              "durationInSeconds": 0,
              "expandedHeight": null,
              "expandedWidth": null,
              "height": "360",
              "htmlResource": null,
              "iFrameResource": null,
              "maintainAspectRatio": false,
              "minSuggestedDuration": null,
              "scalable": false,
              "staticResource": "https://client-side-ads.com/tags/static/ctv-generic/overlay001.json?iv_geo_country%3DUS%26",
              "staticResourceCreativeType": "text/js_ref",
              "width": "640"
            }
          ],
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://adserver.com/beacon=impression"
              ],
              "duration": null,
              "durationInSeconds": 0,
              "eventId": null,
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": null,
              "startTimeInSeconds": 0
            }
          ]
        }
      ],
      "startTime": "PT1M46.08S",
      "startTimeInSeconds": 106.08
    }
  ]
}
```

# Logging and metrics for overlay ads in MediaTailor
<a name="overlay-ads-logging-and-metrics"></a>

This section explains logging and metrics for overlay ads in MediaTailor. For more information about setting up logging, see [Monitoring and tagging AWS Elemental MediaTailor resources](monitoring.md).

**Topics**
+ [CloudWatch logs](#overlay-ads-logging-and-metrics-cloudwatch)
+ [CloudWatch metrics](#overlay-ads-logging-and-metrics-cloudwatch-metrics)

## CloudWatch logs
<a name="overlay-ads-logging-and-metrics-cloudwatch"></a>

CloudWatch collects the following log information about overlay ads:
+ `VAST_RESPONSE` - Shows information about the non-linear ads list.
+ `FILLED_PROVIDER_OVERLAY` - Shows information about the non-linear ads.

**Note**  
The `RAW_ADS_RESPONSE` is an optional event that shows the original response from the ADS. Using this event is especially helpful in a staging and testing environment. To enable this event on a configuration or account, submit a ticket to AWS Support.

## CloudWatch metrics
<a name="overlay-ads-logging-and-metrics-cloudwatch-metrics"></a>

MediaTailor collects overlay ad metrics separately from other ADS metrics. MediaTailor collects these metrics after successfully fetching the ads from the ADS. You don't have to poll the `GetTracking` API to collect the metrics.

The following table describes CloudWatch metrics for overlay ads:


| Metric | Description | 
| --- | --- | 
| AdDecisionServer.OverlayAds |  The count of overlay ads included in the ADS responses within the CloudWatch time period that you specified.  | 
| AdDecisionServer.OverlayErrors |  The number of non-HTTP `200` status code responses, empty responses, and timed-out responses that MediaTailor received from the ADS within the CloudWatch time period that you specified.  | 
| AdDecisionServer.OverlayFilled |  The number of avails that were successfully filled with at least one overlay ad: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediatailor/latest/ug/overlay-ads-logging-and-metrics.html) `SampleCount` tracks the number of avails filled. `Sum` tracks the number of successfully filled overlay avails.  | 
| AdDecisionServer.OverlayMinSuggestedDuration |  The sum of `minSuggestedDuration` durations, in milliseconds, of all ads that MediaTailor received from the ADS within the CloudWatch time period that you specified. If `minSuggestedDuration` isn't specified, the duration shown is the planned duration.  | 
| AdDecisionServer.OverlayLatency |  The response time, in milliseconds, for requests that MediaTailor makes to the ADS.  | 
| AdDecisionServer.OverlayTimeouts |  The number of timed-out requests to the ADS in the CloudWatch time period that you specified.  | 
| AdsBilled |  For more information about ads billed, see [Billing for overlay ads in MediaTailor](overlay-ads-billing.md).  | 
| Avail.\$1 |  Because MediaTailor doesn't do any planning for overlay ads, CloudWatch doesn't show any `Avail.X` metrics.  | 
| SkippedReason.\$1 |  Because MediaTailor doesn't do any planning for overlay ads, CloudWatch doesn't show any `SkippedReason.X` metrics.  | 

# Billing for overlay ads in MediaTailor
<a name="overlay-ads-billing"></a>

MediaTailor bills customers based on the number of non-linear ads in the ADS response. This number includes non-linear ads that extend past the break duration. After MediaTailor fills the avail, it bills for the ads it filled.

For prefetch workflows, MediaTailor does not bill for ads when retrieving the prefetch, but rather, when it sees a compatible ad avail in the consumption window for that session.

For additional billing information, see [https://aws.amazon.com/mediatailor/pricing/](https://aws.amazon.com/mediatailor/pricing/).

# Ad ID decoration
<a name="ad-id-decoration"></a>

AWS Elemental MediaTailor performs server side ad stitching when transitioning from content to ad breaks. MediaTailor can condition the manifest with metadata associated with the ads that have been stitched. Doing so can provide the following benefits:

**Important**  
Ad-ID decoration is not compatible with server-guided ad insertion (SGAI) methods because the fields that populate `X-AD-CREATIVE-SIGNALING `headers are only known when the asset list is fetched during ad playback, not when the cacheable manifest is initially written.
+ *Video start time* (VST) improves
+ MediaTailor can support a hybrid model of server side ad insertion and server guided ad insertion
+ Server side sessions can build playback timelines with ad position markers
+ For client side sessions that already build playback timelines with the MediaTailor API, session VST improves, as the session does not rely on calling the tracking API to build the timeline
+ It's possible to leverage MediaTailor for server side ad insertion as well as client side rendered ads displayed in-scene. This way, a player's software development kit (SDK) doesn't need to have a separate integration to call ad serving entities directly for client-side ads. MediaTailor can vend the ads through the manifest and the client-side tracking API.

There are standards for associating each creative ad asset with a unique identifier. This association allows advertisers, agencies, vendors, and publishers to relate a creative ad asset across their independent workflows. As metrics and monitoring of streams continue to improve and more distributors utilize server-based insertion architectures, the need arises to accurately communicate the identifiers assigned to individual creative assets within an interleaved/stitched presentation, such as within the personalized manifest.

**Topics**
+ [Enabling ad ID signaling for sessions](ad-id-session-state.md)
+ [Manifests and ad metadata insertion](ad-id-manifest.md)
+ [Ad Decision Server (ADS) interactions](ad-id-ads-interactions.md)
+ [Client-side tracking API](ad-id-client-side-tracking-api.md)

# Enabling ad ID signaling for sessions
<a name="ad-id-session-state"></a>

The ad ID signaling feature must be enabled during session initialization. The process to enable the feature differs from creating sessions using the HLS/DASH playback prefix (implicit session initialization), versus the session initialization prefix (explicit session initialization).

**To enable ad ID for the session using HLS/DASH playback prefixes**
+ From the player, initialize a new MediaTailor playback session using a request in one of the following formats, according to your protocol:
  + Example: HLS format

    ```
    GET <mediatailorURL>/v1/master/<hashed-account-id>/<origin-id>/<asset-id>?aws.adSignalingEnabled=true
    ```
  + Example: DASH format

    ```
    GET <mediatailorURL>/v1/dash/<hashed-account-id>/<origin-id>/<asset-id>?aws.adSignalingEnabled=true
    ```

**To enable ad ID for the session using the session initialization prefix**
+ On the player, construct a JSON message body for the session initialization request to MediaTailor: 
  + Inside an `adsParams` object, provide any parameters that MediaTailor should pass to the ADS. These parameters correspond to `[player_params.param]` settings in the ADS template URL of the MediaTailor configuration. 
  + To enable ad ID signaling, add an `adSignaling` object as a top level object, and inside, add a parameter called `enabled` and value of `true`. The default `adSignaling` value is `disabled`.
  + Example: HLS format

    ```
    POST master.m3u8
        {
           "adsParams": {
               "deviceType": "ipad"
           },
           "adSignaling": {
               "enabled": "true"
           },
           "reportingMode": "client"
        }
    ```
  + Example: DASH format

    ```
    POST manifest.mpd
        {
            "adsParams": {
               "deviceType": "ipad"
           },
           "adSignaling": {
                "enabled": "true"
            },
            "reportingMode": "client"
        }
    ```

# Manifests and ad metadata insertion
<a name="ad-id-manifest"></a>

During the ad stitching process, MediaTailor adds to the manifest the unique ID associated with each creative being stitched. MediaTailor obtains the unique ID of the creative from the `id` attribute value of that creative in the VAST response. If the creative lacks an ID attribute value, MediaTailor will publish an empty value (`id=""`).

MediaTailor uses an in-manifest metadata signal to decouple dependencies between the client tracking API for ad creative metadata and timing/positioning within the overall timeline. This decoupling reduces playback latency (especially in VOD scenarios), where the player's user interface (UI) renders ad break positions in the timeline prior to initializing playback.

The added metadata takes the following forms:
+ For HLS manifests, the added metadata takes the form of `DATERANGE` tags for each ad in the avail period.
+ For DASH manifests, the added metadata takes the form of an `Event` element within each ad period.

The following JSON message body shows an example VAST response:

```
{
  "version": 1,
  "identifiers": [
    {
      "scheme": "urn:smpte:ul:060E2B34.01040101.01200900.00000000",
      "value": "creativeId",
      "ad_position": "adId",
      "ad_type": "adType",
      "tracking_uri": "trackingUri",
      "custom_vast_data":"customVastData"
    }
  ]
}
```

In the preceding example:
+ *creativeId* is the `Id` attribute value of the `Creative` element for the ad
+ *adId* is either the HLS sequence number associated with the beginning of the ad, or the DASH period ID of the ad
+ *adType* is either `avail` or `overlay`, based on the VAST response
+ *trackingUri* is the relative tracking endpoint for the MediaTailor session, in the format `../../../../tracking/hashed-account-id/origin-id/session-id`
+ *customVastData* is a value that MediaTailor extracts from the `creative_signaling` VAST extension. MediaTailor uses the contents of the CDATA node, if present. See the [Ad Decision Server (ADS) interactions](ad-id-ads-interactions.md) section for more details and a sample VAST response.

# Personalizing HLS manifests with ad metadata
<a name="ad-id-manifest-hls"></a>

For a live HLS stream, MediaTailor only adds metadata when the stream contains `PROGRAM-DATA-TIME` tags, at least once per manifest duration. For a video on demand (VOD) stream, MediaTailor adds `PROGRAM-DATE-TIME` to at least one segment in the personalized manifest, where the start time for each VOD asset is epoch zero (`1970-01-01T00:00:00Z`). If the origin manifest has existing `PROGRAM-DATE-TIME` content, then MediaTailor preserves that content.

MediaTailor personalizes the manifest with creatives returned by the Ad Decision Server (ADS). For each ad, MediaTailor also includes a `DATERANGE` tag that spans the duration of the ad. The `DATERANGE` tag format is similar to that described in the section [Ad creative signaling in DASH and HLS](https://www.svta.org/document/draft-ad-creative-signaling-in-dash-and-hls/) in the 2023 version of the *SVA technical publication*.

The `DATERANGE` that MediaTailor generates has unique ID values. To ensure uniqueness (given the guidelines specified in [Mapping SCTE-35 into EXT-X-DATERANGE](https://datatracker.ietf.org/doc/html/draft-pantos-http-live-streaming-23#section-4.3.2.7.1)), MediaTailor couples the `MEDIA-SEQUENCE` number of the *first* ad segment of the avail with the sequence number of the ad within the avail.

For underfilled ad breaks on configurations that have slate enabled, MediaTailor appends the slate segments to the end of the avail, separated by a `DISCONTINUITY` tag, but without any `DATERANGE` metadata.

For each ad stitched into the personalized manifest, MediaTailor adds the creative metadata, represented as base64-encoded data in a custom `DATERANGE` tag.

**Example Linear HLS origin (`#EXT-X-CUE-OUT`):**  

```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:7
#EXT-X-MEDIA-SEQUENCE:398
#EXT-X-PROGRAM-DATE-TIME:2023-02-10T19:20:01.397Z
#EXTINF:6.006,
index_1_398.ts?m=1676054627
#EXTINF:5.873,
index_1_399.ts?m=1676054627
#EXT-OATCLS-SCTE35:/DAlAAAAAyiYAP/wFAUAAAACf+//jPl97P4AUmNiAAEBAQAAse4/gA==
#EXT-X-CUE-OUT:59.993
#EXTINF:6.139,
index_1_400.ts?m=1676054627
#EXT-X-CUE-OUT-CONT:ElapsedTime=6.139,Duration=59.993,SCTE35=/DAlAAAAAyiYAP/wFAUAAAACf+//jPl97P4AUmNiAAEBAQAAse4/gA==
#EXTINF:6.006,
index_1_401.ts?m=1676054627
#EXT-X-CUE-OUT-CONT:ElapsedTime=12.145,Duration=59.993,SCTE35=/DAlAAAAAyiYAP/wFAUAAAACf+//jPl97P4AUmNiAAEBAQAAse4/gA==
#EXTINF:6.006,
index_1_402.ts?m=1676054627
#EXT-X-CUE-OUT-CONT:ElapsedTime=18.151,Duration=59.993,SCTE35=/DAlAAAAAyiYAP/wFAUAAAACf+//jPl97P4AUmNiAAEBAQAAse4/gA==
#EXTINF:6.006,
index_1_403.ts?m=1676054627
#EXT-X-CUE-OUT-CONT:ElapsedTime=24.157,Duration=59.993,SCTE35=/DAlAAAAAyiYAP/wFAUAAAACf+//jPl97P4AUmNiAAEBAQAAse4/gA==
#EXTINF:6.006,
index_1_404.ts?m=1676054627
#EXT-X-CUE-OUT-CONT:ElapsedTime=30.163,Duration=59.993,SCTE35=/DAlAAAAAyiYAP/wFAUAAAACf+//jPl97P4AUmNiAAEBAQAAse4/gA==
#EXTINF:6.006,
index_1_405.ts?m=1676054627
#EXT-X-CUE-OUT-CONT:ElapsedTime=36.169,Duration=59.993,SCTE35=/DAlAAAAAyiYAP/wFAUAAAACf+//jPl97P4AUmNiAAEBAQAAse4/gA==
#EXTINF:6.006,
index_1_406.ts?m=1676054627
#EXT-X-CUE-OUT-CONT:ElapsedTime=42.175,Duration=59.993,SCTE35=/DAlAAAAAyiYAP/wFAUAAAACf+//jPl97P4AUmNiAAEBAQAAse4/gA==
#EXTINF:6.006,
index_1_407.ts?m=1676054627
#EXT-X-CUE-OUT-CONT:ElapsedTime=48.181,Duration=59.993,SCTE35=/DAlAAAAAyiYAP/wFAUAAAACf+//jPl97P4AUmNiAAEBAQAAse4/gA==
#EXTINF:6.006,
index_1_408.ts?m=1676054627
#EXT-X-CUE-OUT-CONT:ElapsedTime=54.187,Duration=59.993,SCTE35=/DAlAAAAAyiYAP/wFAUAAAACf+//jPl97P4AUmNiAAEBAQAAse4/gA==
#EXTINF:5.806,
index_1_409.ts?m=1676054627
#EXT-X-CUE-IN
#EXTINF:6.206,
index_1_410.ts?m=1676054627
#EXTINF:6.006,
index_1_411.ts?m=1676054627
#EXTINF:6.006,
index_1_412.ts?m=1676054627
```

**Example Linear HLS origin (`#EXT-X-DATERANGE`):**  

```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:7
#EXT-X-MEDIA-SEQUENCE:25
#EXT-X-PROGRAM-DATE-TIME:2023-02-10T19:19:53.389Z
#EXTINF:6.006,
index_1_25.ts?m=1676056675
#EXTINF:6.006,
index_1_26.ts?m=1676056675
#EXTINF:6.006,
index_1_27.ts?m=1676056675
#EXTINF:1.869,
index_1_28.ts?m=1676056675
#EXT-X-DATERANGE:ID="2",START-DATE="2023-02-10T19:20:13.276Z",PLANNED-DURATION=59.993,SCTE35-OUT=0xFC302500000003289800FFF01405000000027FEFFF8CF97DECFE00526362000101010000B1EE3F80
#EXTINF:6.139,
index_1_29.ts?m=1676056675
#EXTINF:6.006,
index_1_30.ts?m=1676056675
#EXTINF:6.006,
index_1_31.ts?m=1676056675
#EXTINF:6.006,
index_1_32.ts?m=1676056675
#EXTINF:6.006,
index_1_33.ts?m=1676056675
#EXTINF:6.006,
index_1_34.ts?m=1676056675
#EXTINF:6.006,
index_1_35.ts?m=1676056675
#EXTINF:6.006,
index_1_36.ts?m=1676056675
#EXTINF:6.006,
index_1_37.ts?m=1676056675
#EXTINF:5.806,
index_1_38.ts?m=1676056675
#EXT-X-DATERANGE:ID="2",START-DATE="2023-02-10T19:20:13.276Z",END-DATE="2023-02-10T19:21:13.269Z",DURATION=59.993
#EXTINF:6.206,
index_1_39.ts?m=1676056675
#EXTINF:6.006,
index_1_40.ts?m=1676056675
```

**Example Linear HLS personalized manifest (with creative ad signaling):**  
The `DATERANGE` that MediaTailor generates has unique ID values. To ensure uniqueness (given the guidelines specified in [Mapping SCTE-35 into EXT-X-DATERANGE](https://datatracker.ietf.org/doc/html/draft-pantos-http-live-streaming-23#section-4.3.2.7.1)), MediaTailor couples the `MEDIA-SEQUENCE` number of the *first* ad segment of the avail with the sequence number of the ad within the avail.  
In the following example, MediaTailor concatenates `MEDIA-SEQUENCE` 421 with the ad position number.  

```
#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:7
#EXT-X-MEDIA-SEQUENCE:418
#EXT-X-DISCONTINUITY-SEQUENCE:5
#EXT-X-PROGRAM-DATE-TIME:2023-02-10T19:19:55.391Z
#EXTINF:6.006,
https://d3fch9e2fcarly.cloudfront.net/out/v1/1cc7058242a74fdd8aea14e22a9b4131/index_1_397.ts?m=1676054627
#EXTINF:6.006,
https://d3fch9e2fcarly.cloudfront.net/out/v1/1cc7058242a74fdd8aea14e22a9b4131/index_1_398.ts?m=1676054627
#EXTINF:5.873,
https://d3fch9e2fcarly.cloudfront.net/out/v1/1cc7058242a74fdd8aea14e22a9b4131/index_1_399.ts?m=1676054627
#EXT-X-DISCONTINUITY
#EXT-X-PROGRAM-DATE-TIME:2023-02-10T19:19:55.391Z
#EXT-X-DATERANGE:ID="421-1",CLASS="urn:sva:advertising-wg:ad-id-signaling",START-DATE=2019-01-01T00:02:30.000Z,DURATION=15.015,X-AD-CREATIVE-SIGNALING="base64JSON"
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056813
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056814
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056815
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056816
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056817
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056818
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056819
#EXTINF:1.001,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056820
#EXT-X-DISCONTINUITY
#EXT-X-PROGRAM-DATE-TIME:2023-02-10T19:19:55.391Z
#EXT-X-DATERANGE:ID="421-1",START-DATE="2023-02-10T19:36:13.435Z",END-DATE="2023-02-10T19:36:43.432Z",DURATION=15.015
#EXT-X-DATERANGE:ID="421-2",CLASS="urn:sva:advertising-wg:ad-id-signaling",START-DATE=2019-01-01T00:02:30.000Z,DURATION=15.015,X-AD-CREATIVE-SIGNALING="base64JSON"
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056821
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056822
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056823
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056824
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056825
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056826
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056827
#EXTINF:1.001,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056828
#EXT-X-DISCONTINUITY
#EXT-X-PROGRAM-DATE-TIME:2023-02-10T19:19:55.391Z
#EXT-X-DATERANGE:ID="421-2",START-DATE="2023-02-10T19:36:13.435Z",END-DATE="2023-02-10T19:36:43.432Z",DURATION=15.015
#EXT-X-DATERANGE:ID="421-3",CLASS="urn:sva:advertising-wg:ad-id-signaling",START-DATE=2019-01-01T00:02:30.000Z,DURATION=15.015,X-AD-CREATIVE-SIGNALING="base64JSON"
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056829
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056830
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056831
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056832
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056833
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056834
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056835
#EXTINF:1.001,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056836
#EXT-X-DISCONTINUITY
#EXT-X-PROGRAM-DATE-TIME:2023-02-10T19:19:55.391Z
#EXT-X-DATERANGE:ID="421-3",START-DATE="2023-02-10T19:36:13.435Z",END-DATE="2023-02-10T19:36:43.432Z",DURATION=29.997
#EXT-X-DATERANGE:ID="421-4",CLASS="urn:sva:advertising-wg:ad-id-signaling",START-DATE=2019-01-01T00:02:30.000Z,DURATION=15.015,X-AD-CREATIVE-SIGNALING="base64JSON"
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056837
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056838
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056839
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056840
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056841
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056842
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056843
#EXTINF:1.001,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/9e178fa9-dce5-4248-83d2-5b5d98b019bf/0/1676056844
#EXT-X-DISCONTINUITY
#EXT-X-DATERANGE:ID="421-4",START-DATE="2023-02-10T19:36:13.435Z",END-DATE="2023-02-10T19:36:43.432Z",DURATION=15.015
#EXTINF:6.206,
https://d3fch9e2fcarly.cloudfront.net/out/v1/1cc7058242a74fdd8aea14e22a9b4131/index_1_410.ts?m=1676054627
#EXTINF:6.006,
https://d3fch9e2fcarly.cloudfront.net/out/v1/1cc7058242a74fdd8aea14e22a9b4131/index_1_411.ts?m=1676054627
```

**Example VOD HLS origin (with SCTE signals):**  

```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:7
#EXT-X-MEDIA-SEQUENCE:1
#EXT-X-PLAYLIST-TYPE:VOD
#EXTINF:6,
index_720p1500k_00001.ts
#EXTINF:6,
index_720p1500k_00002.ts
#EXTINF:6,
index_720p1500k_00003.ts
#EXTINF:6,
index_720p1500k_00004.ts
#EXTINF:6,
index_720p1500k_00005.ts
#EXT-X-CUE-OUT:0
#EXT-X-CUE-IN
#EXTINF:6,
index_720p1500k_00006.ts
#EXTINF:6,
index_720p1500k_00007.ts
#EXTINF:6,
index_720p1500k_00008.ts
#EXTINF:6,
index_720p1500k_00009.ts
#EXTINF:6,
index_720p1500k_00010.ts
#EXTINF:6,
index_720p1500k_00011.ts
#EXTINF:6,
index_720p1500k_00012.ts
```

**Example VOD HLS origin:**  

```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:7
#EXT-X-MEDIA-SEQUENCE:1
#EXT-X-PLAYLIST-TYPE:VOD
#EXTINF:6,
index_720p1500k_00001.ts
#EXTINF:6,
index_720p1500k_00002.ts
#EXTINF:6,
index_720p1500k_00003.ts
#EXTINF:6,
index_720p1500k_00004.ts
#EXTINF:4,
index_720p1500k_00005.ts
#EXTINF:2,
index_720p1500k_00006.ts
#EXTINF:6,
index_720p1500k_00007.ts
#EXTINF:6,
index_720p1500k_00008.ts
#EXTINF:6,
index_720p1500k_00009.ts
#EXTINF:6,
index_720p1500k_00010.ts
#EXTINF:6,
index_720p1500k_00011.ts
#EXTINF:6,
index_720p1500k_00012.ts
```

**Example VOD HLS personalized manifest:**  
MediaTailor adds `PROGRAM-DATE-TIME` to VOD manifests in order to use them as anchors for the HLS `DATERANGE` elements that indicate ad positions.  
The `DATERANGE` that MediaTailor generates has unique ID values. To ensure uniqueness (given the guidelines specified in [Mapping SCTE-35 into EXT-X-DATERANGE](https://datatracker.ietf.org/doc/html/draft-pantos-http-live-streaming-23#section-4.3.2.7.1)), MediaTailor couples the `MEDIA-SEQUENCE` number of the *first* ad segment of the avail with the sequence number of the ad within the avail.  
In the following example, MediaTailor concatenates `MEDIA-SEQUENCE` 421 with the ad position number.  

```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-TARGETDURATION:7
#EXT-X-MEDIA-SEQUENCE:1
#EXT-X-DISCONTINUITY-SEQUENCE:0
#EXT-X-PROGRAM-DATE-TIME:1970-01-01T00:00:00Z
#EXTINF:6.0,
https://d3fch9e2fcarly.cloudfront.net/cunsco-media/SKO-22/asset-1/hls/index_720p1500k_00001.ts
#EXTINF:6.0,
https://d3fch9e2fcarly.cloudfront.net/cunsco-media/SKO-22/asset-1/hls/index_720p1500k_00002.ts
#EXTINF:6.0,
https://d3fch9e2fcarly.cloudfront.net/cunsco-media/SKO-22/asset-1/hls/index_720p1500k_00003.ts
#EXTINF:6.0,
https://d3fch9e2fcarly.cloudfront.net/cunsco-media/SKO-22/asset-1/hls/index_720p1500k_00004.ts
#EXTINF:4.0,
https://d3fch9e2fcarly.cloudfront.net/cunsco-media/SKO-22/asset-1/hls/index_720p1500k_00005.ts
#EXT-X-DISCONTINUITY
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/28
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/29
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/30
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/31
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/32
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/33
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/34
#EXTINF:1.001,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/35
#EXT-X-DISCONTINUITY
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/36
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/37
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/38
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/39
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/40
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/41
#EXTINF:2.002,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/42
#EXTINF:1.001,
../../../../segment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/vod-variations/9810d863-8736-45fa-866e-be6d2c2bfa20/0/43
#EXT-X-DISCONTINUITY
#EXTINF:2.0,
https://d3fch9e2fcarly.cloudfront.net/cunsco-media/SKO-22/asset-1/hls/index_720p1500k_00006.ts
#EXTINF:6.0,
https://d3fch9e2fcarly.cloudfront.net/cunsco-media/SKO-22/asset-1/hls/index_720p1500k_00007.ts
#EXTINF:6.0,
https://d3fch9e2fcarly.cloudfront.net/cunsco-media/SKO-22/asset-1/hls/index_720p1500k_00008.ts
#EXTINF:6.0,
https://d3fch9e2fcarly.cloudfront.net/cunsco-media/SKO-22/asset-1/hls/index_720p1500k_00009.ts
#EXTINF:6.0,
https://d3fch9e2fcarly.cloudfront.net/cunsco-media/SKO-22/asset-1/hls/index_720p1500k_00010.ts
#EXTINF:6.0,
https://d3fch9e2fcarly.cloudfront.net/cunsco-media/SKO-22/asset-1/hls/index_720p1500k_00011.ts
#EXTINF:6.0,
https://d3fch9e2fcarly.cloudfront.net/cunsco-media/SKO-22/asset-1/hls/index_720p1500k_00012.ts
#EXT-X-ENDLIST
#EXT-X-DATERANGE:ID="5-1",START-DATE="1970-01-01T00:00:28.000Z",END-DATE="1970-01-01T00:00:43.015Z",DURATION=15.015
#EXT-X-DATERANGE:ID="5-2",START-DATE="1970-01-01T00:00:43.015Z",END-DATE="1970-01-01T00:00:58.030Z",DURATION=15.01
```

# Personalizing DASH manifests with ad metadata
<a name="ad-id-manifest-dash"></a>

MediaTailor personalizes the manifest with creatives returned by the Ad Decision Server (ADS). For each ad, MediaTailor also includes an `EventStream` element that spans the duration of the ad. The `Event` element format is similar to that described in the section [Ad creative signaling in DASH and HLS](https://www.svta.org/document/draft-ad-creative-signaling-in-dash-and-hls/) in the 2023 version of the *SVA technical publication*.

For underfilled ad breaks on configurations that have slate enabled, MediaTailor appends the slate period to the end of the avail period, but without any `EventStream` metadata

For each ad stitched into the personalized manifest, MediaTailor adds the creative metadata, represented as a `CDATA` element within an `Event` element.

**Example Linear DASH origin (Inline SCTE attributes):**  

```
<MPD xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:mpeg:dash:schema:mpd:2011" xmlns:scte35="urn:scte:scte35:2013:xml" xsi:schemaLocation="urn:mpeg:dash:schema:mpd:2011 http://standards.iso.org/ittf/PubliclyAvailableStandards/MPEG-DASH_schema_files/DASH-MPD.xsd" id="201" type="dynamic" publishTime="2023-02-10T21:08:40+00:00" minimumUpdatePeriod="PT6S" availabilityStartTime="2023-02-09T22:47:05.865000+00:00" minBufferTime="PT10S" suggestedPresentationDelay="PT20.000S" timeShiftBufferDepth="PT88.999S" profiles="urn:mpeg:dash:profile:isoff-live:2011">
  <Period start="PT80141.456S" id="104" duration="PT304.103S">
    <AdaptationSet id="1485523442" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1" bitstreamSwitching="true">
      <SegmentTemplate timescale="60000" media="index_video_$RepresentationID$_0_$Number$.mp4?m=1676062374" initialization="index_video_$RepresentationID$_0_init.mp4?m=1676062374" startNumber="151" presentationTimeOffset="4808487386">
        <SegmentTimeline>
          <S t="4824975858" d="360360" r="3"/>
          <S t="4826417298" d="316316"/>
        </SegmentTimeline>
      </SegmentTemplate>
      <Representation id="1" width="960" height="540" frameRate="30000/1001" bandwidth="1800000" codecs="avc1.4D401F"/>
      <Representation id="3" width="640" height="360" frameRate="30000/1001" bandwidth="1200000" codecs="avc1.4D401E"/>
      <Representation id="5" width="480" height="270" frameRate="30000/1001" bandwidth="800000" codecs="avc1.4D4015"/>
    </AdaptationSet>
    <AdaptationSet id="1377232898" mimeType="audio/mp4" segmentAlignment="0" lang="eng">
      <Label>eng</Label>
      <SegmentTemplate timescale="48000" media="index_audio_$RepresentationID$_0_$Number$.mp4?m=1676062374" initialization="index_audio_$RepresentationID$_0_init.mp4?m=1676062374" startNumber="151" presentationTimeOffset="3846790126">
        <SegmentTimeline>
          <S t="3859981294" d="287744"/>
          <S t="3860269038" d="288768"/>
          <S t="3860557806" d="287744"/>
          <S t="3860845550" d="288768"/>
          <S t="3861134318" d="252928"/>
        </SegmentTimeline>
        </SegmentTemplate>
        <Representation id="2" bandwidth="193007" audioSamplingRate="48000" codecs="mp4a.40.2">
        <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
      </Representation>
      <Representation id="4" bandwidth="193007" audioSamplingRate="48000" codecs="mp4a.40.2">
        <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
      </Representation>
      <Representation id="6" bandwidth="193007" audioSamplingRate="48000" codecs="mp4a.40.2">
        <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
      </Representation>
    </AdaptationSet>
    <SupplementalProperty schemeIdUri="urn:scte:dash:utc-time" value="2023-02-10T21:02:31.007Z"/>
  </Period>
  <Period start="PT80445.560S" id="155" duration="PT44.978S">
    <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2013:xml">
      <Event duration="4048044">
        <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="207000" tier="4095">
          <scte35:SpliceInsert spliceEventId="111" spliceEventCancelIndicator="false" outOfNetworkIndicator="true" spliceImmediateFlag="false" uniqueProgramId="1" availNum="1" availsExpected="1">
            <scte35:Program>
              <scte35:SpliceTime ptsTime="7239893422"/>
            </scte35:Program>
            <scte35:BreakDuration autoReturn="true" duration="4048044"/>
          </scte35:SpliceInsert>
        </scte35:SpliceInfoSection>
      </Event>
    </EventStream>
    <AdaptationSet id="1485523442" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1" bitstreamSwitching="true">
      <SegmentTemplate timescale="60000" media="index_video_$RepresentationID$_0_$Number$.mp4?m=1676062374" initialization="index_video_$RepresentationID$_0_init.mp4?m=1676062374" startNumber="156" presentationTimeOffset="4826733614">
        <SegmentTimeline>
          <S t="4826733614" d="284284"/>
          <S t="4827017898" d="360360" r="5"/>
          <S t="4829180058" d="252252"/>
        </SegmentTimeline>
      </SegmentTemplate>
      <Representation id="1" width="960" height="540" frameRate="30000/1001" bandwidth="1800000" codecs="avc1.4D401F"/>
      <Representation id="3" width="640" height="360" frameRate="30000/1001" bandwidth="1200000" codecs="avc1.4D401E"/>
      <Representation id="5" width="480" height="270" frameRate="30000/1001" bandwidth="800000" codecs="avc1.4D4015"/>
    </AdaptationSet>
    <AdaptationSet id="1377232898" mimeType="audio/mp4" segmentAlignment="0" lang="eng">
      <Label>eng</Label>
      <SegmentTemplate timescale="48000" media="index_audio_$RepresentationID$_0_$Number$.mp4?m=1676062374" initialization="index_audio_$RepresentationID$_0_init.mp4?m=1676062374" startNumber="156" presentationTimeOffset="3861387246">
        <SegmentTimeline>
          <S t="3861387246" d="227328"/>
          <S t="3861614574" d="288768"/>
          <S t="3861903342" d="287744"/>
          <S t="3862191086" d="288768"/>
          <S t="3862479854" d="287744"/>
          <S t="3862767598" d="288768"/>
          <S t="3863056366" d="287744"/>
          <S t="3863344110" d="202752"/>
        </SegmentTimeline>
      </SegmentTemplate>
      <Representation id="2" bandwidth="193007" audioSamplingRate="48000" codecs="mp4a.40.2">
        <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
      </Representation>
      <Representation id="4" bandwidth="193007" audioSamplingRate="48000" codecs="mp4a.40.2">
        <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
      </Representation>
      <Representation id="6" bandwidth="193007" audioSamplingRate="48000" codecs="mp4a.40.2">
        <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
      </Representation>
    </AdaptationSet>
    <SupplementalProperty schemeIdUri="urn:scte:dash:utc-time" value="2023-02-10T21:07:35.111Z"/>
  </Period>
  <Period start="PT80490.538S" id="163">
    <AdaptationSet id="1485523442" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1" bitstreamSwitching="true">
      <SegmentTemplate timescale="60000" media="index_video_$RepresentationID$_0_$Number$.mp4?m=1676062374" initialization="index_video_$RepresentationID$_0_init.mp4?m=1676062374" startNumber="164" presentationTimeOffset="4829432310">
        <SegmentTimeline>
          <S t="4829432310" d="348348"/>
          <S t="4829780658" d="360360" r="1"/>
        </SegmentTimeline>
      </SegmentTemplate>
      <Representation id="1" width="960" height="540" frameRate="30000/1001" bandwidth="1800000" codecs="avc1.4D401F"/>
      <Representation id="3" width="640" height="360" frameRate="30000/1001" bandwidth="1200000" codecs="avc1.4D401E"/>
      <Representation id="5" width="480" height="270" frameRate="30000/1001" bandwidth="800000" codecs="avc1.4D4015"/>
    </AdaptationSet>
    <AdaptationSet id="1377232898" mimeType="audio/mp4" segmentAlignment="0" lang="eng">
      <Label>eng</Label>
      <SegmentTemplate timescale="48000" media="index_audio_$RepresentationID$_0_$Number$.mp4?m=1676062374" initialization="index_audio_$RepresentationID$_0_init.mp4?m=1676062374" startNumber="164" presentationTimeOffset="3863546862">
        <SegmentTimeline>
          <S t="3863546862" d="278528"/>
          <S t="3863825390" d="287744"/>
          <S t="3864113134" d="288768"/>
        </SegmentTimeline>
      </SegmentTemplate>
      <Representation id="2" bandwidth="193007" audioSamplingRate="48000" codecs="mp4a.40.2">
        <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
      </Representation>
      <Representation id="4" bandwidth="193007" audioSamplingRate="48000" codecs="mp4a.40.2">
        <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
      </Representation>
      <Representation id="6" bandwidth="193007" audioSamplingRate="48000" codecs="mp4a.40.2">
        <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
      </Representation>
    </AdaptationSet>
    <SupplementalProperty schemeIdUri="urn:scte:dash:utc-time" value="2023-02-10T21:08:20.090Z"/>
  </Period>
</MPD>
```

**Example Linear DASH personalized manifest (with creative ad signaling):**  

```
<MPD availabilityStartTime="2023-02-09T22:47:05.865000+00:00" id="201" minBufferTime="PT10S" minimumUpdatePeriod="PT6S" profiles="urn:mpeg:dash:profile:isoff-live:2011" publishTime="2023-02-10T21:08:43+00:00" suggestedPresentationDelay="PT20.000S" timeShiftBufferDepth="PT88.999S" 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://d3fch9e2fcarly.cloudfront.net/out/v1/f9f38deca3f14fc4b5ab3cdbd76cfb9e/</BaseURL>
    <Location>https://777788889999.mediatailor.us-west-2.amazonaws.com/v1/dash/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/out/v1/f9f38deca3f14fc4b5ab3cdbd76cfb9e/index.mpd?aws.sessionId=672ed481-4ffd-4270-936f-7c8403947f2e</Location>
    <Period duration="PT304.103S" id="104" start="PT80141.456S">
        <AdaptationSet bitstreamSwitching="true" id="1485523442" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1">
            <SegmentTemplate initialization="index_video_$RepresentationID$_0_init.mp4?m=1676062374" media="index_video_$RepresentationID$_0_$Number$.mp4?m=1676062374" presentationTimeOffset="4808487386" startNumber="151" timescale="60000">
                <SegmentTimeline>
                    <S d="360360" r="3" t="4824975858"/>
                    <S d="316316" t="4826417298"/>
                </SegmentTimeline>
            </SegmentTemplate>
            <Representation bandwidth="1800000" codecs="avc1.4D401F" frameRate="30000/1001" height="540" id="1" width="960"/>
            <Representation bandwidth="1200000" codecs="avc1.4D401E" frameRate="30000/1001" height="360" id="3" width="640"/>
            <Representation bandwidth="800000" codecs="avc1.4D4015" frameRate="30000/1001" height="270" id="5" width="480"/>
        </AdaptationSet>
        <AdaptationSet id="1377232898" lang="eng" mimeType="audio/mp4" segmentAlignment="0">
            <Label>eng</Label>
            <SegmentTemplate initialization="index_audio_$RepresentationID$_0_init.mp4?m=1676062374" media="index_audio_$RepresentationID$_0_$Number$.mp4?m=1676062374" presentationTimeOffset="3846790126" startNumber="151" timescale="48000">
                <SegmentTimeline>
                    <S d="287744" t="3859981294"/>
                    <S d="288768" t="3860269038"/>
                    <S d="287744" t="3860557806"/>
                    <S d="288768" t="3860845550"/>
                    <S d="252928" t="3861134318"/>
                </SegmentTimeline>
            </SegmentTemplate>
            <Representation audioSamplingRate="48000" bandwidth="193007" codecs="mp4a.40.2" id="2">
                <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
            </Representation>
            <Representation audioSamplingRate="48000" bandwidth="193007" codecs="mp4a.40.2" id="4">
                <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
            </Representation>
            <Representation audioSamplingRate="48000" bandwidth="193007" codecs="mp4a.40.2" id="6">
                <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
            </Representation>
        </AdaptationSet>
        <SupplementalProperty schemeIdUri="urn:scte:dash:utc-time" value="2023-02-10T21:02:31.007Z"/>
    </Period>
    <Period id="155_1" start="PT22H20M45.56S">
        <BaseURL>https://777788889999.mediatailor.us-west-2.amazonaws.com/v1/dashsegment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/672ed481-4ffd-4270-936f-7c8403947f2e/155/155_1/</BaseURL>
        <EventStream schemeIdUri="urn:sva:advertising-wg:ad-id-signaling" timescale="90000">
            <Event presentationTime="xxxxx" duration="1351350">
                <![CDATA[{"version": 1,"identifiers": [{"scheme": "urn:smpte:ul:060E2B34.01040101.01200900.00000000","value": "155_1","ad_position": "155_1", "ad_type":"avail","creative_id": "123","tracking_uri": "../../../../v1/tracking/hashed-account-id/origin-id/session-id","custom_vast_data":"123abc"}]}]]>
            </Event>
        </EventStream>
        <AdaptationSet bitstreamSwitching="false" frameRate="30000/1001" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1">
            <SegmentTemplate startNumber="1" timescale="90000"/>
            <Representation bandwidth="1800000" codecs="avc1.64001f" height="540" id="1" width="960">
                <SegmentTemplate initialization="asset_540_1_2init.mp4" media="asset_540_1_2_$Number%09d$.mp4" startNumber="1" timescale="90000">
                    <SegmentTimeline>
                        <S d="180180" r="6" t="0"/>
                        <S d="90090" t="1261260"/>
                    </SegmentTimeline>
                </SegmentTemplate>
            </Representation>
            <Representation bandwidth="1200000" codecs="avc1.64001e" height="360" id="3" width="640">
                <SegmentTemplate initialization="asset_360_1_1init.mp4" media="asset_360_1_1_$Number%09d$.mp4" startNumber="1" timescale="90000">
                    <SegmentTimeline>
                        <S d="180180" r="6" t="0"/>
                        <S d="90090" t="1261260"/>
                    </SegmentTimeline>
                </SegmentTemplate>
            </Representation>
            <Representation bandwidth="800000" codecs="avc1.640015" height="270" id="5" width="480">
                <SegmentTemplate initialization="asset_270_0_0init.mp4" media="asset_270_0_0_$Number%09d$.mp4" startNumber="1" timescale="90000">
                    <SegmentTimeline>
                        <S d="180180" r="6" t="0"/>
                        <S d="90090" t="1261260"/>
                    </SegmentTimeline>
                </SegmentTemplate>
            </Representation>
        </AdaptationSet>
        <AdaptationSet lang="eng" mimeType="audio/mp4" segmentAlignment="0">
            <SegmentTemplate initialization="asset_audio_128_3init.mp4" media="asset_audio_128_3_$Number%09d$.mp4" startNumber="1" timescale="48000"/>
            <Label>eng</Label>
            <Representation audioSamplingRate="48000" bandwidth="128000" codecs="mp4a.40.2" id="6">
                <SegmentTemplate initialization="asset_audio_128_3init.mp4" media="asset_audio_128_3_$Number%09d$.mp4" startNumber="1" timescale="48000">
                    <SegmentTimeline>
                        <S d="98304" t="0"/>
                        <S d="96256" r="1" t="98304"/>
                        <S d="95232" t="290816"/>
                        <S d="96256" r="2" t="386048"/>
                        <S d="48128" t="674816"/>
                    </SegmentTimeline>
                </SegmentTemplate>
                <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
            </Representation>
        </AdaptationSet>
    </Period>
    <Period id="155_2" start="PT22H21M0.575S">
        <BaseURL>https://777788889999.mediatailor.us-west-2.amazonaws.com/v1/dashsegment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/672ed481-4ffd-4270-936f-7c8403947f2e/155/155_2/</BaseURL>
        <EventStream schemeIdUri="urn:sva:advertising-wg:ad-id-signaling" timescale="90000">
            <Event presentationTime="0" duration="1351350">
                <![CDATA[{"version": 1,"identifiers": [{"scheme": "urn:smpte:ul:060E2B34.01040101.01200900.00000000","value": "155_2","ad_position": "155_2", "ad_type":"avail","creative_id": "234","tracking_uri": "../../../../v1/tracking/hashed-account-id/origin-id/session-id","custom_vast_data":"123abc"}]}]]>
            </Event>
        </EventStream>
        <AdaptationSet bitstreamSwitching="false" frameRate="30000/1001" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1">
            <SegmentTemplate startNumber="1" timescale="90000"/>
            <Representation bandwidth="1800000" codecs="avc1.64001f" height="540" id="1" width="960">
                <SegmentTemplate initialization="asset_540_1_2init.mp4" media="asset_540_1_2_$Number%09d$.mp4" startNumber="1" timescale="90000">
                    <SegmentTimeline>
                        <S d="180180" r="6" t="0"/>
                        <S d="90090" t="1261260"/>
                    </SegmentTimeline>
                </SegmentTemplate>
            </Representation>
            <Representation bandwidth="1200000" codecs="avc1.64001e" height="360" id="3" width="640">
                <SegmentTemplate initialization="asset_360_1_1init.mp4" media="asset_360_1_1_$Number%09d$.mp4" startNumber="1" timescale="90000">
                    <SegmentTimeline>
                        <S d="180180" r="6" t="0"/>
                        <S d="90090" t="1261260"/>
                    </SegmentTimeline>
                </SegmentTemplate>
            </Representation>
            <Representation bandwidth="800000" codecs="avc1.640015" height="270" id="5" width="480">
                <SegmentTemplate initialization="asset_270_0_0init.mp4" media="asset_270_0_0_$Number%09d$.mp4" startNumber="1" timescale="90000">
                    <SegmentTimeline>
                        <S d="180180" r="6" t="0"/>
                        <S d="90090" t="1261260"/>
                    </SegmentTimeline>
                </SegmentTemplate>
            </Representation>
        </AdaptationSet>
        <AdaptationSet lang="eng" mimeType="audio/mp4" segmentAlignment="0">
            <SegmentTemplate initialization="asset_audio_128_3init.mp4" media="asset_audio_128_3_$Number%09d$.mp4" startNumber="1" timescale="48000"/>
            <Label>eng</Label>
            <Representation audioSamplingRate="48000" bandwidth="128000" codecs="mp4a.40.2" id="6">
                <SegmentTemplate initialization="asset_audio_128_3init.mp4" media="asset_audio_128_3_$Number%09d$.mp4" startNumber="1" timescale="48000">
                    <SegmentTimeline>
                        <S d="98304" t="0"/>
                        <S d="96256" r="1" t="98304"/>
                        <S d="95232" t="290816"/>
                        <S d="96256" r="2" t="386048"/>
                        <S d="48128" t="674816"/>
                    </SegmentTimeline>
                </SegmentTemplate>
                <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
            </Representation>
        </AdaptationSet>
    </Period>
    <Period id="155_3" start="PT22H21M15.59S">
        <BaseURL>https://777788889999.mediatailor.us-west-2.amazonaws.com/v1/dashsegment/94063eadf7d8c56e9e2edd84fdf897826a70d0df/emt/672ed481-4ffd-4270-936f-7c8403947f2e/155/155_3/</BaseURL>
        <EventStream schemeIdUri="urn:sva:advertising-wg:ad-id-signaling" timescale="90000">
            <Event presentationTime="0" duration="1351350">
                <![CDATA[{"version": 1,"identifiers": [{"scheme": "urn:smpte:ul:060E2B34.01040101.01200900.00000000","value": "155_3","ad_position": "155_3", "ad_type":"avail","creative_id": "345","tracking_uri": "../../../../v1/tracking/hashed-account-id/origin-id/session-id","custom_vast_data":"123abc"}]}]]>
            </Event>
        </EventStream>
        <AdaptationSet bitstreamSwitching="false" frameRate="30000/1001" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1">
            <SegmentTemplate startNumber="1" timescale="90000"/>
            <Representation bandwidth="1800000" codecs="avc1.64001f" height="540" id="1" width="960">
                <SegmentTemplate initialization="asset_540_1_2init.mp4" media="asset_540_1_2_$Number%09d$.mp4" startNumber="1" timescale="90000">
                    <SegmentTimeline>
                        <S d="180180" r="6" t="0"/>
                        <S d="90090" t="1261260"/>
                    </SegmentTimeline>
                </SegmentTemplate>
            </Representation>
            <Representation bandwidth="1200000" codecs="avc1.64001e" height="360" id="3" width="640">
                <SegmentTemplate initialization="asset_360_1_1init.mp4" media="asset_360_1_1_$Number%09d$.mp4" startNumber="1" timescale="90000">
                    <SegmentTimeline>
                        <S d="180180" r="6" t="0"/>
                        <S d="90090" t="1261260"/>
                    </SegmentTimeline>
                </SegmentTemplate>
            </Representation>
            <Representation bandwidth="800000" codecs="avc1.640015" height="270" id="5" width="480">
                <SegmentTemplate initialization="asset_270_0_0init.mp4" media="asset_270_0_0_$Number%09d$.mp4" startNumber="1" timescale="90000">
                    <SegmentTimeline>
                        <S d="180180" r="6" t="0"/>
                        <S d="90090" t="1261260"/>
                    </SegmentTimeline>
                </SegmentTemplate>
            </Representation>
        </AdaptationSet>
        <AdaptationSet lang="eng" mimeType="audio/mp4" segmentAlignment="0">
            <SegmentTemplate initialization="asset_audio_128_3init.mp4" media="asset_audio_128_3_$Number%09d$.mp4" startNumber="1" timescale="48000"/>
            <Label>eng</Label>
            <Representation audioSamplingRate="48000" bandwidth="128000" codecs="mp4a.40.2" id="6">
                <SegmentTemplate initialization="asset_audio_128_3init.mp4" media="asset_audio_128_3_$Number%09d$.mp4" startNumber="1" timescale="48000">
                    <SegmentTimeline>
                        <S d="98304" t="0"/>
                        <S d="96256" r="1" t="98304"/>
                        <S d="95232" t="290816"/>
                        <S d="96256" r="2" t="386048"/>
                        <S d="48128" t="674816"/>
                    </SegmentTimeline>
                </SegmentTemplate>
                <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
            </Representation>
        </AdaptationSet>
    </Period>
    <Period id="163" start="PT80490.538S">
        <AdaptationSet bitstreamSwitching="true" id="1485523442" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1">
            <SegmentTemplate initialization="index_video_$RepresentationID$_0_init.mp4?m=1676062374" media="index_video_$RepresentationID$_0_$Number$.mp4?m=1676062374" presentationTimeOffset="4829432310" startNumber="164" timescale="60000">
                <SegmentTimeline>
                    <S d="348348" t="4829432310"/>
                    <S d="360360" r="1" t="4829780658"/>
                </SegmentTimeline>
            </SegmentTemplate>
            <Representation bandwidth="1800000" codecs="avc1.4D401F" frameRate="30000/1001" height="540" id="1" width="960"/>
            <Representation bandwidth="1200000" codecs="avc1.4D401E" frameRate="30000/1001" height="360" id="3" width="640"/>
            <Representation bandwidth="800000" codecs="avc1.4D4015" frameRate="30000/1001" height="270" id="5" width="480"/>
        </AdaptationSet>
        <AdaptationSet id="1377232898" lang="eng" mimeType="audio/mp4" segmentAlignment="0">
            <Label>eng</Label>
            <SegmentTemplate initialization="index_audio_$RepresentationID$_0_init.mp4?m=1676062374" media="index_audio_$RepresentationID$_0_$Number$.mp4?m=1676062374" presentationTimeOffset="3863546862" startNumber="164" timescale="48000">
                <SegmentTimeline>
                    <S d="278528" t="3863546862"/>
                    <S d="287744" t="3863825390"/>
                    <S d="288768" t="3864113134"/>
                </SegmentTimeline>
            </SegmentTemplate>
            <Representation audioSamplingRate="48000" bandwidth="193007" codecs="mp4a.40.2" id="2">
                <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
            </Representation>
            <Representation audioSamplingRate="48000" bandwidth="193007" codecs="mp4a.40.2" id="4">
                <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
            </Representation>
            <Representation audioSamplingRate="48000" bandwidth="193007" codecs="mp4a.40.2" id="6">
                <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
            </Representation>
        </AdaptationSet>
        <SupplementalProperty schemeIdUri="urn:scte:dash:utc-time" value="2023-02-10T21:08:20.090Z"/>
    </Period>
</MPD>
```

# Ad Decision Server (ADS) interactions
<a name="ad-id-ads-interactions"></a>

MediaTailor uses the creative `id` attribute value from the VAST response as a value in the ad ID signaling. If the `id` attribute value is empty or not present in the VAST response, MediaTailor places an empty value in the ad ID signaling.

**Example VAST response:**  
The following sample VAST response includes an `id` attribute value for the inline linear `Creative`. MediaTailor extracts the value from the custom VAST `Extension` element and places that value in the creative metadata of the manifest.  

```
<?xml version="1.0" encoding="utf-8"?>
<VAST version="3.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Ad sequence="3">
        <InLine>
            <AdSystem>2.0</AdSystem>
            <AdTitle>AD-caribbean2-15</AdTitle>
            <Impression><![CDATA[https://n8ljfs0xxx.execute-api.us-west-2.amazonaws.com/v1/impression]]></Impression>
            <Creatives>
                <Creative sequence="3" apiFramework="inLine" id="1234">
                    <Linear>
                        <Duration>00:00:15</Duration>
                        <MediaFiles>
                            <MediaFile id="00002" delivery="progressive" type="video/mp4" width="1280" height="720"><![CDATA[https://d3re4i3vgppxxx.cloudfront.net/Media/Bumpers/AD-caribbean2-15-HD.mp4]]></MediaFile>
                        </MediaFiles>
                    </Linear>
                </Creative>
            </Creatives>
          <Extensions>
            <Extension type="creative_signaling"><![CDATA[999999|TVNlDDNpFTchtpRj,E5TfTtcYd5IEzvEt,ChA05OHcvWRGFY6Zp5VSSlxUEJ2B9p8GGhQIDzIQkFeQC-Ho67FR3P9qNa6khSAGKgAyAA]]></Extension>
          </Extensions>
        </InLine>
    </Ad>
</VAST>
```

# Client-side tracking API
<a name="ad-id-client-side-tracking-api"></a>

The following example shows how a player SDK links the ad metadata in the manifest with the full tracking event data in the client-side tracking response payload with `creativeId` and `adId`.

**Example JSON message:**  

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "ads": [
        {
          "adId": "5",
          "adParameters": "",
          "adProgramDateTime": null,
          "adSystem": "2.0",
          "adTitle": "AD-caribbean2-15",
          "adVerifications": [],
          "companionAds": [],
          "creativeId": "1234",
          "creativeSequence": "2",
          "duration": "PT15S",
          "durationInSeconds": 15,
          "extensions": [],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": null,
          "startTime": "PT30S",
          "startTimeInSeconds": 30,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://myServer/impression"
              ],
              "duration": "PT15S",
              "durationInSeconds": 15,
              "eventId": "5",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT30S",
              "startTimeInSeconds": 30
            }
          ],
          "vastAdId": ""
        }
      ],
      "availId": "5",
      "availProgramDateTime": null,
      "duration": "PT15S",
      "durationInSeconds": 15,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT30S",
      "startTimeInSeconds": 30
    }
  ],
  "nextToken": "UFQ1TTM0Ljk2N1NfMjAyMi0xMS0xOFQwNDozMzo1Mi4yNDUxOTdaXzE%3D",
  "nonLinearAvails": []
}
```