AWS Elemental MediaTailor Session Initialization - Part 1: Core Concepts
Start your MediaTailor integration with confidence: understand what a session is, how its parameters behave, and how to choose the initialization approach that best fits your goals.
AWS Elemental MediaTailor Session Initialization, Part 1 of 3
This is the first article in a three-part series on session initialization in AWS Elemental MediaTailor:
- Part 1 (this article): Core Concepts covers what a session is and how to choose your initialization approach.
- Part 2: Explicit & Implicit walks through implementing explicit and implicit initialization.
- Part 3: Parameter Routing covers parameter routing and the practical gotchas that break ad requests.
Introduction
So you've got a MediaTailor playback configuration, an origin serving content, and an ad decision server ready to go. Now you need to actually start a session. How you do that first step matters more than you might think, and it is one of the most common sources of integration issues we see in the field.
When a viewer presses play on an ad-supported stream, a chain of interactions begins between the video player, your CDN, AWS Elemental MediaTailor, your content origin, and your ad decision server (ADS). At the center of this chain is a concept called session initialization, the process by which MediaTailor creates a unique, personalized viewing session for each viewer.
Session initialization is the first interaction between your application and MediaTailor. It determines how ads are selected, how ad reporting is performed, and how parameters flow between the components in your streaming workflow. Getting session initialization right is foundational to a successful MediaTailor integration.
During session initialization, MediaTailor:
- Creates a unique session for the viewer, identified by a session ID
- Accepts parameters that control ad targeting, CDN routing, and origin behavior
- Sets those parameters for the lifetime of the session
- Returns a personalized manifest URL (and optionally a tracking URL) for the player to consume
This series covers what a MediaTailor session is, how to choose between the two initialization approaches (explicit and implicit), how each approach works in practice, and how parameters are passed and routed. This first article focuses on the foundations: what a session is, and how to decide between explicit and implicit initialization before you write any code.
What is a MediaTailor Session?
A MediaTailor session represents a single viewer's personalized stream. Every viewer watching the same live channel or VOD asset gets their own session with its own ad decisions, because each session carries its own set of targeting parameters. When a session is created, MediaTailor assigns a unique session ID, visible in the personalized manifest URLs, that ties all subsequent requests to that viewer's ad decisions. This includes manifest requests, segment requests, and ad reporting events.
Session Lifecycle
A session begins when MediaTailor processes a session initialization request from your application. The two methods for triggering this request (explicit and implicit) are covered in detail in Part 2 .
A session expires after a period of inactivity equal to 10 times the manifest duration , subject to a minimum of 10 minutes and a maximum of 24 hours. This is not configurable. When the session expires, MediaTailor returns an HTTP 400 (Bad Request) response.
Session Immutability
Once a session is created, its parameters are set for the session's lifetime. This is a critical concept to understand: MediaTailor ignores all query parameters on manifest requests made after the session has been established. Adding, removing, or modifying parameters on subsequent manifest requests for an active session has no effect on the manifests returned. For the full details on this behavior, see Parameter session behavior and persistence .
This immutability extends to configuration changes as well. If you update your MediaTailor configuration (for example, changing the ADS URL template or modifying a transcode profile), those changes only apply to new sessions. Running sessions continue to use the configuration that was active when they were initialized.
Choosing Your Approach: Explicit vs Implicit
MediaTailor supports two methods for session initialization: explicit and implicit. For almost all implementations, explicit session initialization is the recommended approach. Implicit initialization is appropriate only in limited scenarios.
Use implicit session initialization when:
- All parameters are non-sensitive. If your session initialization request contains no sensitive parameters, such as private targeting data or business logic you want to keep server-side, implicit initialization avoids the need for a server-side component.
- You are evaluating players during a proof of concept. Implicit URLs are self-contained GET requests that can be pasted directly into web player demos (hls.js, Shaka Player, dash.js) with no server-side code required. This makes them ideal for quickly testing MediaTailor's capabilities across different players.
Use explicit session initialization for everything else. This includes any deployment where you need client-side ad reporting, programmatic ad buyer compatibility, parameter privacy, or structured control over session options.
Why Explicit is Recommended
Programmatic ad buyers increasingly require verification that ads were rendered on the viewer's device. This verification is provided through IAB Open Measurement (an industry standard for independent ad viewability verification), which gives the buy side confidence in inventory quality and enables access to premium programmatic demand.
Client-side reporting SDKs such as Datazoom simplify this by handling ad event reporting and IAB Open Measurement verification for MediaTailor sessions, without requiring custom reporting code. For a detailed walkthrough of client-side reporting setup, see Client-side reporting with MediaTailor (upcoming).
Explicit session initialization is the only way to receive a structured tracking URL in the session response, which these SDKs require. While implicit sessions can enable client-side reporting via aws.reportingMode=CLIENT, no tracking URL is returned, and targeting parameters are exposed in the manifest URL. Starting with explicit initialization keeps targeting parameters server-side and puts you on the path to client-side measurement from day one, minimizing rework as your ad monetization matures.
Combined with the need to keep targeting parameters server-side, the recommended production pattern is: server-side explicit session initialization with client-side reporting using a reporting SDK.
Typical Integration Progression
Most implementations follow a natural progression through session initialization approaches as the integration matures:
- PoC / Player Evaluation: Use implicit session initialization to quickly test MediaTailor with different players. Paste implicit URLs directly into web player demos to validate ad stitching, manifest handling, and player compatibility with no server-side code.
- Initial Production Deployment: Move to explicit session initialization with server-side reporting. This keeps targeting parameters server-side, enables structured parameter control through the POST body, and provides a foundation for production ad insertion.
- Full Ad Monetization: Implement a client-side SDK (e.g., Datazoom) and switch to explicit session initialization with client-side reporting. This enables programmatic ad buyer compatibility, IAB Open Measurement support, and independent ad reporting.
Each stage builds on the previous one. The transition from implicit to explicit requires adding a server-side session initialization call. The transition from server-side to client-side reporting requires integrating a reporting SDK on the client and passing the trackingUrl from the session initialization response.
Comparison
| Consideration | Explicit (Recommended) | Implicit |
|---|---|---|
| Client-side ad reporting | Supported | Supported via aws.reportingMode=CLIENT (no structured tracking URL returned) |
| Programmatic ad buyer compatibility | Full (structured SDK integration with separate tracking URL) | Possible but impractical (no structured tracking URL for SDK integration) |
| Parameter visibility | Server-side only | All params visible to client in URL |
| Complex parameter structures | Nested objects (e.g., availSuppression with mode, value, fillPolicy) | Flat query strings only |
| SDK integration (Datazoom, etc.) | Supported (manifestUrl + trackingUrl separation) | Not supported (no separate tracking URL) |
| Integration complexity | Higher (init call + manifest request) | Lower (single GET request) |
| Reporting mode | Server-side or client-side | Server-side (default) or client-side via aws.reportingMode=CLIENT |
| Ad ID signaling | Via JSON body | Via query param only |
| Best for | Production deployments with ad monetization | PoCs, player testing, non-sensitive server-side ad insertion (SSAI) |
Part 2 covers each approach in detail, starting with explicit session initialization.
Continue to Part 2: Explicit & Implicit , where we implement both approaches step by step.
Further Reading
AWS Elemental MediaTailor Session Initialization series
- Part 1: Core Concepts (this article)
- Part 2: Explicit & Implicit
- Part 3: Parameter Routing
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article