AWS Elemental MediaTailor Session Initialization - Part 2: Explicit & Implicit

Put session initialization into practice with step-by-step examples for the explicit POST flow and the implicit HLS and DASH GET flows.

Andrew

Published Jun 15, 2026

Last modified Jun 15, 2026

AWS Elemental MediaTailor Session Initialization, Part 2 of 3

This is Part 2 of a three-part series on AWS Elemental MediaTailor session initialization. Part 1: Core Concepts covered what a session is and how to choose between explicit and implicit initialization. This article shows how to implement each approach in practice. If you haven't read Part 1, start there, the explicit-vs-implicit decision drives everything below.

This article covers each approach in detail, starting with explicit session initialization.

Explicit Session Initialization

With explicit session initialization, your application makes a dedicated POST request to MediaTailor's session endpoint before the player requests any manifests. MediaTailor creates the session, processes the initialization parameters, and returns a JSON response containing the URLs the player needs.

Constructing the URL

The session initialization URL is assembled from three components:
The console shows the native MediaTailor endpoint. In production you front this with your CDN domain, as described above.

Screenshot of the AWS Elemental MediaTailor console Content and origin details tab, showing the Playback endpoint prefixes panel with the Playback endpoint prefix, Session initialization prefix, HLS playback prefix, and DASH playback prefix fields. The AWS account ID is redacted.

CDN domain: The domain of the CDN that routes requests to MediaTailor (e.g., https://cdn.example.com). In a MediaTailor workflow, the CDN handles both manifest and segment delivery, so all requests, including session initialization, are routed through it.
Session initialization prefix: The path provided by your MediaTailor playback configuration as the SessionInitializationEndpointPrefix (labeled "Session initialization prefix" in the console). This includes the /v1/session/ path segment, your hashed account ID, and the origin ID.
Origin manifest path: The path to the specific manifest on your content origin server.

1
<CDN domain><session initialization prefix><origin manifest path>[?query parameters]

For example, given:

CDN domain: https://cdn.example.com
Session initialization prefix: /v1/session/777788889999/myOrigin
Origin manifest path: /out/v1/channel/index.m3u8

The full URL would be:

1
POST https://cdn.example.com/v1/session/777788889999/myOrigin/out/v1/channel/index.m3u8?aws.manifestsettings=start:1709000000

Only origin parameters (such as time-shift filters) appear as query parameters on the POST URL. All other parameters, including player parameters and manifest parameters, are passed in the JSON body (see POST Body Structure below).

For the full reference, see explicit session initialization in the service documentation.

Response

The response contains two URLs:

manifestUrl: the personalized manifest URL for the player
trackingUrl: the ad reporting endpoint used by client-side SDKs (when using client-side reporting)

Important: MediaTailor returns both URLs as relative paths, not full URLs. The server initiating the session must prepend the domain of the CDN delivering the content before passing these URLs to the player or reporting SDK.

Example request:

1
2
3
4
5
6
7
8
9
10
11
12
13
POST https://cdn.example.com/v1/session/777788889999/myOrigin/index.m3u8
Content-Type: application/json

{
  "playerParams": {
    "user_id": "abc123",
    "genre": "sports"
  },
  "manifestParams": {
    "cdn_token": "xyz"
  },
  "reportingMode": "client"
}

Example response:

1
2
3
4
{
  "manifestUrl": "/v1/master/777788889999/myOrigin/index.m3u8?aws.sessionId=1a2b3c4d-5678-90ab-cdef-example11111&cdn_token=xyz",
  "trackingUrl": "/v1/tracking/777788889999/myOrigin/1a2b3c4d-5678-90ab-cdef-example11111?cdn_token=xyz"
}

After prepending the CDN domain, the full URLs become:

1
2
Manifest: https://cdn.example.com/v1/master/777788889999/myOrigin/index.m3u8?aws.sessionId=1a2b3c4d-5678-90ab-cdef-example11111&cdn_token=xyz
Tracking: https://cdn.example.com/v1/tracking/777788889999/myOrigin/1a2b3c4d-5678-90ab-cdef-example11111?cdn_token=xyz

Notice that the cdn_token manifest parameter appears in both URLs. MediaTailor appends manifest parameters to all URLs it generates, ensuring consistent CDN authorization throughout the session.

POST Body Structure

The POST body provides structured separation of parameters by purpose. Each key routes parameters to a different destination:

Key	Purpose	Destination
`playerParams`	Ad targeting and personalization	Substituted into the ADS URL template as player variables
`manifestParams`	CDN routing and authorization	Appended to all manifest and segment URLs
`reportingMode`	Ad reporting method	Controls server-side vs client-side reporting
`insertionMode`	Ad insertion method	`STITCHED` (default) or `GUIDED`
`availSuppression`	Ad break suppression rules	Controls when ad breaks are suppressed
`adSignaling`	Ad ID decoration	Enables ad ID metadata in manifests
`streamId`	Prefetch matching	Links session to prefetched ad decisions

Origin parameters (such as time-shift filters) are passed as query parameters on the POST URL itself, not in the JSON body. For example:

1
2
3
4
5
6
7
8
POST /v1/session/777788889999/myOrigin/index.m3u8?aws.manifestfilter=start:1709000000;end:1709003600
Content-Type: application/json

{
  "playerParams": { "genre": "sports" },
  "manifestParams": { "cdn_token": "xyz" },
  "reportingMode": "client"
}

The following example shows a POST body using more of the available options:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "streamId": "myStreamId",
  "reportingMode": "server",
  "insertionMode": "GUIDED",
  "availSuppression": {
    "mode": "BEHIND_LIVE_EDGE",
    "value": "00:00:21",
    "fillPolicy": "FULL_AVAIL_ONLY"
  },
  "adSignaling": {
    "enabled": true
  },
  "playerParams": {
    "param1": "value1",
    "param2": "value2"
  },
  "manifestParams": {
    "cdn_token": "xyz"
  }
}

Note that some session-level options like availSuppression use nested object structures. This is one of the advantages of explicit initialization over implicit, where all parameters must be expressed as flat query strings.

Note: The adsParams and playerParams keys in the POST body are synonyms, both route parameters to the ADS URL template via [player_params.*] substitution. When both are provided, playerParams values take precedence on key conflicts. The playerParams key is the recommended key going forward, and adsParams remains fully supported for backward compatibility.

Server-Side Session Initialization

Explicit initialization enables the session to be created entirely server-side, typically within your service's playback API. The server makes the POST to MediaTailor, receives the JSON response, and returns only the manifestUrl (and optionally the trackingUrl) to the client player. The player never sees the original initialization request or its parameters.

Client-Side SDK Integration

The separation of manifestUrl and trackingUrl in the explicit initialization response enables a clean division of responsibilities on the client: the player receives the manifestUrl and handles video playback, while a reporting SDK (such as Datazoom) receives the trackingUrl and handles ad event reporting and IAB Open Measurement independently.

Implicit session initialization does not return a separate trackingURL in a structured response. While client-side reporting is technically possible with implicit sessions, the player must construct the tracking URL manually from the session ID. For this reason, if your integration requires client-side ad reporting with an SDK, explicit session initialization is the recommended approach.

Implicit Session Initialization

With implicit session initialization, the player configures the session through query parameters on a GET request to the manifest URL. There is no separate initialization call and no POST body. All session parameters, including ADS targeting, manifest routing, and origin parameters, are encoded directly in the URL.

This is the simplest integration path: construct a URL with the appropriate parameters and pass it to the player. The URL can be pasted directly into web player demos like hls.js or Shaka Player for quick testing.

The trade-off is that all parameters are visible in the manifest request URL, and there is no structured response providing a separate tracking URL for client-side ad reporting SDKs. How MediaTailor handles the response differs between HLS and DASH, as described in the sections below.

Constructing the URL

Like explicit initialization, the implicit URL is assembled from three components:

CDN domain: The domain of the CDN that routes requests to MediaTailor.
Playback prefix: The path provided by your MediaTailor playback configuration, which differs by stream type:
- HLS: The HLS playback prefix in the console (path begins with /v1/master/)
- DASH: The DASH playback prefix in the console (path begins with /v1/dash/)
- Both are derived from the configuration's PlaybackEndpointPrefix and include your hashed account ID and origin ID.
Origin manifest path: The path to the specific manifest on your content origin server.

1
<CDN domain><playback prefix><origin manifest path>[?query parameters]

For example, given:

CDN domain: https://cdn.example.com
HLS playback prefix: /v1/master/777788889999/myOrigin
Origin manifest path: /out/v1/channel/index.m3u8

The full URL would be:

1
GET https://cdn.example.com/v1/master/777788889999/myOrigin/out/v1/channel/index.m3u8?playerParams.genre=sports&manifest.cdn_token=xyz

All parameters (player, manifest, and origin) are appended as query parameters on this URL using the prefixes described below.

Parameter Prefixes

Implicit initialization uses query parameter names and prefixes to determine how each parameter is routed:

Parameter or Prefix	Routed To	Consumed by MediaTailor?	Example
`playerParams.*`	Ad Decision Server (ADS)	Yes, substituted into ADS URL template	`playerParams.genre=sports`
`ads.*`	Ad Decision Server (ADS)	Yes, synonym for `playerParams.*`	`ads.genre=sports`
`manifest.*`	Appended to manifest/segment URLs (prefix stripped)	Yes, used for CDN routing	`manifest.cdn_token=xyz` → `cdn_token=xyz`
`aws.reportingMode`, `aws.insertionMode`, `aws.logMode`, `aws.adSignalingEnabled`, `aws.overlayAvails`, `aws.availSuppression*`, `aws.streamId`	Not forwarded	Yes, MediaTailor session configuration	`aws.reportingMode=CLIENT`
`aws.manifestfilter`, `aws.manifestsettings`, `aws.drmsettings`	Origin server	No, passed through unchanged	`aws.manifestfilter=video_height:360`
(no recognised prefix)	Origin server	No, passed through unchanged	`start=1648080000`

HLS Implicit Initialization

For HLS content, the implicit initialization URL follows this pattern:

1
GET /v1/master/<hashed-account-id>/<originId>/<path-to-manifest>.m3u8

Example request:

1
GET https://cdn.example.com/v1/master/777788889999/myOrigin/out/v1/myOrigin/myChannel/cmaf/index.m3u8?manifest.cdn_token=xyz&playerParams.genre=sports

MediaTailor creates a session and returns the multivariant playlist. In the response, notice three things:

The session ID is embedded in the path of each media playlist URL (e.g., /manifest/<hash>/<originId>/<sessionId>/<variant>.m3u8), not as a query parameter
The cdn_token manifest parameter appears as a query parameter on each URL, with the manifest. prefix stripped
The playerParams.genre parameter does not appear in the manifest. It is stored as part of the session and substituted into the ADS URL template whenever MediaTailor makes an ad request, provided the template includes a corresponding [player_params.genre] variable.

Manifest parameters propagate through the entire manifest hierarchy: multivariant playlist, media playlists, and segment URLs all carry the same parameters, ensuring consistent CDN authorization throughout the session. For more detail on how parameters flow through manifests, see Manifest query parameters .

Sequence diagram of HLS implicit session initialization. The player sends a GET request to the HLS playback URL with player and manifest parameters; MediaTailor returns the multivariant playlist with the session ID embedded in each media playlist path; the player requests a media playlist and receives it with segment URLs carrying the manifest parameters (prefix stripped).

DASH Implicit Initialization

For DASH content, the implicit initialization URL follows a different pattern (see DASH implicit session initialization ):

1
GET /v1/dash/<hashed-account-id>/<originId>/<manifest>.mpd

Example request:

1
GET https://cdn.example.com/v1/dash/777788889999/myOrigin/index.mpd?manifest.cdn_token=xyz&playerParams.genre=sports

Unlike HLS, DASH implicit initialization involves a redirect. MediaTailor responds with an HTTP 302 redirect to the same URL with the aws.sessionId parameter appended:

1
2
HTTP/1.1 302 Found
Location: /v1/dash/777788889999/myOrigin/index.mpd?manifest.cdn_token=xyz&playerParams.genre=sports&aws.sessionId=1a2b3c4d-5678-90ab-cdef-example11111

The player follows the redirect and receives the MPD. The key differences from HLS:

The session ID appears as the aws.sessionId query parameter (via the 302 redirect), rather than being embedded in the URL path
Manifest parameters (e.g., cdn_token) are propagated into SegmentTemplate URLs within the MPD, ensuring CDN authorization applies to ad content

Sequence diagram of DASH implicit session initialization. The player sends a GET request to the DASH playback URL with player and manifest parameters; MediaTailor responds with an HTTP 302 redirect whose Location appends aws.sessionId; the player follows the redirect and receives the MPD, with manifest parameters propagated into the SegmentTemplate URLs.

Part 3: Parameter Routing goes deeper into how these parameters are routed and the practical gotchas that can break ad requests.

Builder Center

AWS Elemental MediaTailor Session Initialization - Part 2: Explicit & Implicit

Andrew

Explicit Session Initialization

Constructing the URL

Response

POST Body Structure

Server-Side Session Initialization

Implicit Session Initialization

Constructing the URL

Parameter Prefixes

HLS Implicit Initialization

DASH Implicit Initialization

Further Reading