View a markdown version of this page

MediaTailor server-guided ad insertion overview and implementation - AWS Elemental MediaTailor
Enable in the playback configurationCreate a server-guided session

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

To let players use server-guided ad insertion, set the insertion mode on the playback configuration to allow player selection:

  • In the MediaTailor console, on the playback configuration, set Insertion mode to Player select.

  • In the PutPlaybackConfiguration API, AWS CLI, or AWS CloudFormation, set InsertionMode to PLAYER_SELECT.

With this setting, players can select either stitched or guided ad insertion when the session initializes. The other option, Stitched only (STITCHED_ONLY), is the default. It requires every session to use server-side (stitched) ad insertion. While the configuration is set to Stitched only, players can't use server-guided ad insertion, and a player that requests it fails to initialize the session. A player that connects to a Player select configuration but doesn't request a mode uses stitched insertion by default. For more information about insertion mode, see Ad insertion mode.

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.

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.