# MediaTailor server-side ad tracking and reporting
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 /v1/master///?ads.&
```
+ Example: DASH format
```
GET /v1/dash///?ads.&
```
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)
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
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=&awsBeaconDomain=&awsConfigurationName="
}
]
}
```
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
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
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
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
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
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
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
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
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
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
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
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
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
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