# MediaTailor server-guided ad insertion overview and implementation
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
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
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
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
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
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
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=`) 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
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
### Ad prefetching
Ad prefetching isn't currently supported.
### Ad suppression
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
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
**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
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
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
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
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
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
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
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=`) 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
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
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
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
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
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
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
VOD content enables unique ad targeting opportunities:
### Content metadata targeting
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
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
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
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
Optimize your SGAI VOD implementation for maximum performance:
### Cache optimization
+ **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
+ **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