AWS Elemental MediaTailor Session Initialization - Part 3: Parameter Routing
How player, manifest, and origin parameters are routed to the ADS, CDN, and origin, plus practical guidance on URL encoding, error handling, length limits, and debugging for reliable ad insertion.
AWS Elemental MediaTailor Session Initialization, Part 3 of 3
This is the final article in a three-part series on AWS Elemental MediaTailor session initialization. Part 1: Core Concepts covered session concepts and choosing an approach. Part 2: Explicit & Implicit covered implementing explicit and implicit initialization. This article goes deeper into parameter routing and the practical details that affect your integration.
Understanding Parameters
Part 2 introduced how parameters are passed during session initialization. This article goes deeper into the three categories of parameters, their routing behavior, and the practical details that affect your integration. For the full reference on parameter routing, see Parameter routing for ADS and origins .
Origin Parameters
Origin parameters are passed through to the content origin server (e.g., AWS Elemental MediaPackage). They control origin-specific functionality such as time-shifted viewing, content filtering, and authentication.
| Implicit | Explicit | |
|---|---|---|
| How to pass | No recognised prefix, any parameter not prefixed with playerParams., ads., or manifest., and not a recognised aws. session parameter (see tables below) | Query parameters on the POST URL |
| Example | ?aws.manifestfilter=video_height:360 | POST /v1/session/.../index.m3u8?aws.manifestfilter=video_height:360 |
Common use cases:
- Time-shifted content with MediaPackage: aws.manifestsettings=start:<epoch>;end:<epoch> for startover and catch-up viewing
- Manifest filtering with MediaPackage: aws.manifestfilter=video_height:360 to filter renditions
- DRM output control with MediaPackage V2: aws.drmsettings=exclude_session_keys:true
- Time-shift start/end: start=<epoch>&end=<epoch>
- Any parameters the origin server requires for content processing
The aws.* prefix: origin parameters vs session parameters
The aws. prefix is shared between MediaPackage origin parameters and MediaTailor session configuration parameters. This can be confusing because some aws.* parameters pass through to the origin while others are consumed by MediaTailor and never reach the origin.
Origin parameters (passed through to MediaPackage):
MediaTailor includes these in its internal cache key but forwards them to the origin unchanged.
| Parameter | Purpose | Documentation |
|---|---|---|
| aws.manifestfilter | Content filtering (codec, bitrate, resolution, language, audio channels) | Manifest filtering query parameters |
| aws.manifestsettings | Time-shifted viewing (start time, end time, manifest window duration) | Time-shifted query parameters |
| aws.drmsettings | DRM output control (e.g., exclude session keys) | MediaPackage V2 |
| start | Time-shift start time (no aws. prefix) | Start and end parameters |
| end | Time-shift end time (no aws. prefix) | Start and end parameters |
Session parameters (consumed by MediaTailor, not forwarded):
| Parameter | Purpose |
|---|---|
| aws.sessionId | Session identifier |
| aws.reportingMode | Server-side (SERVER) or client-side (CLIENT) reporting |
| aws.insertionMode | Stitched (STITCHED) or guided (GUIDED) ad insertion |
| aws.adSignalingEnabled | Ad ID decoration in manifests |
| aws.overlayAvails | Enable (on) or disable (off) overlay ads |
| aws.logMode | Debug logging (DEBUG) |
| aws.availSuppressionMode | Avail suppression mode |
| aws.availSuppressionValue | Avail suppression time value |
| aws.availSuppressionFillPolicy | Avail suppression fill policy |
| aws.streamId | Prefetch schedule matching |
Rule of thumb: If a query parameter uses the aws. prefix but is not in the session parameters table above, MediaTailor treats it as an origin parameter and passes it through unchanged.
Player Parameters (ADS Targeting)
MediaTailor stores player parameters as part of the session and substitutes them into the ADS URL template wherever [player_params.<key>] variables are configured. MediaTailor does not send them to the ADS at session creation time. Instead, it substitutes them into the ADS URL each time it makes an ad request for the session.
| Implicit | Explicit | |
|---|---|---|
| How to pass | playerParams.* prefix (or ads.*) | playerParams object in POST body (or adsParams) |
| Example | ?playerParams.genre=sports | { "playerParams": { "genre": "sports" } } |
Common use cases:
- Viewer demographics and preferences
- Content genre or category for contextual targeting
- Device type or platform identifiers
- Custom targeting parameters required by the ADS
URL encoding behavior:
- Server-side reporting: MediaTailor URL-decodes parameter values once before substituting them into the ADS request. If your ADS expects URL-encoded values, you must double-encode them.
- Client-side reporting: Values from the JSON payload are passed unaltered to the ADS.
This encoding difference is a common source of issues when switching between reporting modes. If ad requests start failing after changing from server-side to client-side reporting (or vice versa), check whether parameter values need to be encoded differently.
Manifest Parameters
Manifest parameters are appended to all manifest and segment URLs that MediaTailor generates. They are primarily used for CDN authorization and routing.
| Implicit | Explicit | |
|---|---|---|
| How to pass | manifest.* prefix | manifestParams object in POST body |
| Example | ?manifest.cdn_token=xyz | { "manifestParams": { "cdn_token": "xyz" } } |
Key behavior: The manifest. prefix is stripped from the output URLs. For example, manifest.cdn_token=xyz in the request becomes cdn_token=xyz on all manifest and segment URLs in the response.
Common use cases:
- CDN authorization tokens (e.g., CloudFront signed URL parameters)
- Dynamic CDN routing parameters
- Content access control tokens
Note: Manifest parameter pass-through must be enabled for your account by AWS Support before use. Without enablement, manifestParams values will not appear on generated URLs.
Session Parameters Reference
The following table provides a consolidated reference of MediaTailor-defined parameters that can be specified during session initialization, with their POST body key and implicit query parameter equivalent.
| Parameter | POST Body Key | Implicit Query Param | Description | Values |
|---|---|---|---|---|
| Reporting Mode | reportingMode | aws.reportingMode | Server or client-side ad reporting | server, client |
| Insertion Mode | insertionMode | aws.insertionMode | Stitched or guided ad insertion | STITCHED, GUIDED |
| Avail Suppression | availSuppression | aws.availSuppressionMode, aws.availSuppressionValue, aws.availSuppressionFillPolicy | Control ad break suppression | Object: mode, value, fillPolicy |
| Ad Signaling | adSignaling | aws.adSignalingEnabled | Enable ad ID decoration | { "enabled": true } / =true |
| Overlay Avails | overlayAvails | aws.overlayAvails | Enable/disable overlay ads | on, off |
| Stream ID | streamId | aws.streamId | Identifier for prefetch matching | String |
| Log Mode | logMode | aws.logMode | Enable debug logging for session | DEBUG |
| Player Params | playerParams | playerParams.* | ADS targeting parameters | Key-value pairs |
| Manifest Params | manifestParams | manifest.* | CDN routing parameters | Key-value pairs |
Note that parameters with nested object structures (e.g., availSuppression with its mode, value, and fillPolicy fields) have implicit equivalents expressed as separate flat query parameters (aws.availSuppressionMode, aws.availSuppressionValue, aws.availSuppressionFillPolicy). This is functionally equivalent but less convenient than the structured JSON body used with explicit initialization.
Configuration Aliases
If your ADS URL template uses domain variables (e.g., [player_params.ads_domain]), every possible value must have a corresponding configuration alias . A request with an unaliased value returns HTTP 400. Aliases also help keep URLs within length limits by mapping short player parameter values to longer actual values.
Practical Considerations
Error Handling
When session initialization fails, MediaTailor returns standard HTTP error codes:
| Code | Cause | Action |
|---|---|---|
| 400 | Malformed request body, invalid JSON, missing configuration alias, or invalid parameter values | Log the response body for debugging. Do not retry, the request must be corrected. |
| 403 | Authorization failure | Verify IAM permissions and request signing. |
| 5xx | MediaTailor service error | Implement retry with exponential backoff. |
For server-side explicit initialization, your playback API should handle these errors gracefully.
CDN Caching
Personalized manifest responses must not be cached by the CDN, as each response is unique to a session and contains viewer-specific ad decisions. CDN cache behavior configuration for MediaTailor is covered in detail in the CDN integration article.
URL Encoding
MediaTailor's URL encoding behavior differs between reporting modes (see Player Parameters above). Beyond that, be aware of these common pitfalls:
- Avoid double-encoding parameter values unless your ADS specifically expects URL-encoded values in the request
- Special characters in player parameter values (e.g., &, =, +) must be properly URL-encoded to avoid being interpreted as query string delimiters
- When switching between server-side and client-side reporting, test that your ADS receives parameter values in the expected encoding
Parameter Length Limits
MediaTailor enforces the following limits on parameters during session initialization:
| Limit | Value |
|---|---|
| Manifest query parameters (total) | 2,000 characters |
| ADS parameter names | 10,000 characters |
| ADS parameter values | 25,000 characters |
| ADS URL (total, after variable substitution) | 25,000 characters |
If your ADS URL exceeds 25,000 characters after MediaTailor substitutes all variables, the ad request will fail. Use configuration aliases to shorten long parameter values if you are approaching these limits.
Debugging
To troubleshoot session initialization and ad request issues, enable debug logging for a session. How you enable it depends on your initialization method:
- Implicit: Pass aws.logMode=DEBUG as a query parameter on the manifest request
- Explicit: Include "logMode": "DEBUG" in the POST body of the session initialization request
MediaTailor writes detailed logs to CloudWatch, including:
- The resolved ADS URL with all variables substituted
- The ADS response (VAST or VMAP ad payload)
- Manifest generation events
Use the MediaTailor/AdDecisionServerInteractions CloudWatch Logs log group to verify that player parameters are being substituted correctly into your ADS URL template. A maximum of 10 debug sessions can be active simultaneously.
Live vs VOD
Session initialization works the same way for both live and VOD content. The one difference is in how MediaTailor handles ad breaks for VOD assets without SCTE-35 ad markers (the in-band signals that indicate ad break opportunities): MediaTailor makes a single ADS request for the entire asset. If the ADS returns a VAST (Video Ad Serving Template) response, MediaTailor inserts all ads as pre-roll. If a VMAP (Video Multiple Ad Playlist) response is returned, ads are inserted at the cue points specified in the VMAP.
Summary
Across this series, we covered how MediaTailor sessions are created, configured, and maintained. Here are the key takeaways:
Sessions are immutable. Parameters are locked at initialization and cannot be changed for the lifetime of the session. Configuration changes only affect new sessions.
Use explicit session initialization for production deployments. It enables server-side parameter protection, client-side ad reporting through a separate tracking URL, and structured control over session options through the POST body.
Use implicit session initialization for PoCs and player testing. Implicit URLs are self-contained GET requests that can be pasted directly into web player demos with no server-side code.
Understand parameter routing. Player parameters go to the ADS, manifest parameters go to the CDN, and origin parameters go to the content origin. How you pass them depends on whether you use implicit (prefixed query strings) or explicit (structured JSON body) initialization.
Quick Reference
| Explicit | Implicit HLS | Implicit DASH | |
|---|---|---|---|
| Request method | POST /v1/session/... | GET /v1/master/... | GET /v1/dash/... |
| Session ID location | In manifestUrl response path | In media playlist URL path | aws.sessionId query param (via 302 redirect) |
| Tracking URL | Returned in response | Not returned in response | Not returned in response |
| Player params | playerParams in POST body | playerParams.* prefix | playerParams.* prefix |
| Manifest params | manifestParams in POST body | manifest.* prefix | manifest.* prefix |
| Origin params | Query params on POST URL | No prefix | No prefix |
| Reporting mode | Server-side or client-side | Server-side (default) or client-side via aws.reportingMode | Server-side (default) or client-side via aws.reportingMode |
Further Reading
- Integrating a CDN with MediaTailor
- Parameter routing for ADS and origins
- Player variables for ADS requests
- Configuration aliases
- Client-side ad reporting
- Debug logging
AWS Elemental MediaTailor Session Initialization series
- Part 1: Core Concepts
- Part 2: Explicit & Implicit
- Part 3: Parameter Routing (this article)
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article