Prerequisites Step 1: Access MediaTailor Step 2: Prepare a stream Step 3: Configure ADS request URL and query parameters Step 4: Create a configuration Step 5: Test the configuration Step 6: Send the playback request to MediaTailor (Optional) step 7: Monitor activity Step 8: Clean up

Getting started with MediaTailor ad insertion

To use AWS Elemental MediaTailor, you need an AWS account and permissions to access, view, and edit MediaTailor configurations. For information on how to do this, see Setting up AWS Elemental MediaTailor.

This Getting Started tutorial shows you how to perform the following tasks:

Prepare your HLS or DASH content streams
Configure an ad decision server (ADS) template URL
Create a MediaTailor configuration that contains a playback endpoint
Use your player or content delivery network (CDN) to make a playback request to MediaTailor

When you're finished, you'll be able to send a playback request to MediaTailor for personalized ad content in your stream.

Topics

Prerequisites
Step 1: Access AWS Elemental MediaTailor
Step 2: Prepare a stream
Step 3: Configure ADS request URL and query parameters
Step 4: Create a configuration
Step 5: Test the configuration
Step 6: Send the playback request to AWS Elemental MediaTailor
Step 7 (optional): Monitor AWS Elemental MediaTailor activity
Step 8: Clean up

Prerequisites

Before you begin, be sure that you've completed the steps in Setting up AWS Elemental MediaTailor.

Step 1: Access AWS Elemental MediaTailor

Using your IAM credentials, sign in to the MediaTailor console at https://console.aws.amazon.com/mediatailor/home.

Step 2: Prepare a stream

Configure your origin server to produce manifests for HLS or DASH that are compatible with AWS Elemental MediaTailor.

Prepare an HLS stream

HLS manifests must satisfy the following requirements:

Manifests must be accessible on the public internet.
Manifests must be live or video on demand (VOD).
Manifests must have an EXT-X-VERSION of 3 or higher.
For live content, manifests must contain markers to delineate ad avails. This is optional for VOD content, which can use VMAP timeoffsets instead.

The manifest file must have ad slots marked with one of the following:
- #EXT-X-CUE-OUT / #EXT-X-CUE-IN (more common) with durations as shown in the following example.
```
#EXT-X-CUE-OUT:60.00
#EXT-X-CUE-IN
```
- #EXT-X-DATERANGE (less common) with durations as shown in the following example.
```
#EXT-X-DATERANGE:ID="",START-DATE="",DURATION=30.000,SCTE35-OUT=0xF
#EXT-X-DATERANGE:ID="",START-DATE="",DURATION=30.000,SCTE35-OUT=0xF
```
  All fields shown for #EXT-X-DATERANGE are required.
The way that you configure the ad markers in the manifest influences whether ads are inserted in a stream or replace other fragments in the stream. For more information, see Understanding MediaTailor ad insertion behavior.
HLS master manifests must follow the HLS specification documented at HTTP live streaming: Master playlist tags. In particular, #EXT-X-STREAM-INF must include the fields RESOLUTION, BANDWIDTH, and CODEC.

After you have configured the stream, note the content origin URL prefix for the master manifest. You need it to create the configuration in AWS Elemental MediaTailor, later in this tutorial.

Prepare a DASH stream

DASH manifests must satisfy the following requirements:

Manifests must be accessible on the public internet.
Manifests must be live or video on demand (VOD).
Manifests must mark events as ad avails using either splice insert markers or time signal markers. You can provide the ad markers in clear XML or in base64-encoded binary. For splice insert, the out-of-network indicator must be enabled. For time signal markers, the segmentation type ID, located inside the segmentation UPID, must be a cue-out value recognized by AWS Elemental MediaTailor. The ad avail starts at the event start and lasts for the event duration, if one is specified, or until the next event starts.

The following example shows an event designated as an ad avail using splice insert markers. The duration for this ad avail is the event's duration.
```
  <Period start="PT444806.040S" id="123586" duration="PT15.000S">
    <EventStream timescale="90000" schemeIdUri="urn:scte:scte35:2013:xml">
      <Event duration="1350000">
        <scte35:SpliceInfoSection protocolVersion="0" ptsAdjustment="180832" tier="4095">
          <scte35:SpliceInsert spliceEventId="4026531855" spliceEventCancelIndicator="false" outOfNetworkIndicator="true" spliceImmediateFlag="false" uniqueProgramId="1" availNum="1" availsExpected="1">
            <scte35:Program><scte35:SpliceTime ptsTime="5672624400"/></scte35:Program>
            <scte35:BreakDuration autoReturn="true" duration="1350000"/>
          </scte35:SpliceInsert>
        </scte35:SpliceInfoSection>
      </Event>
    </EventStream>
    <AdaptationSet mimeType="video/mp4"
        ...
    </AdaptationSet>
  </Period>
```

Ad avails must have the same AdaptationSet and Representation settings as content streams. AWS Elemental MediaTailor uses these settings to transcode the ads to match the content stream, for smooth switching between the two.

After you configure the stream, note the content origin URL prefix for the DASH manifest. You need it to create the configuration in AWS Elemental MediaTailor, later in this tutorial.

Step 3: Configure ADS request URL and query parameters

To determine the query parameters that the ADS requires, generate an ad tag URL from the ADS. This URL acts as a template for requests to the ADS, and consists of the following:

Static values
Values generated by AWS Elemental MediaTailor (denoted by session or avail query parameters)
Values generated by players, obtained from the client application (denoted by player_params. query parameters)

Example Ad tag URL from an ADS


https://my.ads.com/ad?output=vast&content_id=12345678&playerSession=[session.id]&cust_params=[player_params.cust_params]

Where:

output and content_id are static values
playerSession=[session.id] is a dynamic value provided by AWS Elemental MediaTailor. The value of [session.id] changes for each player session and results in a different URL for the VAST request for each session.
cust_params are player-supplied dynamic values

The master manifest request from the player must provide key-value pairs that correspond to the player_params. query parameters in the ADS request URL. For more information about configuring key-value pairs in the request to AWS Elemental MediaTailor, see Using dynamic ad variables in AWS Elemental MediaTailor.

Enter the configured "template" URL when you create the origin server/ADS mapping in MediaTailor, in Step 4: Create a configuration.

Testing

You can use a static VAST response from your ADS for testing purposes. Ideally, the VAST response returns a mezzanine quality MP4 rendition that AWS Elemental MediaTailor can transcode. If the response from the ADS contains multiple playback renditions, MediaTailor picks the highest quality and resolution MP4 rendition and sends it to the transcoder.

Step 4: Create a configuration

The AWS Elemental MediaTailor configuration holds mapping information for the origin server and ADS.

To create a configuration (console)

Open the MediaTailor console at https://console.aws.amazon.com/mediatailor/.
On the Configurations page, choose Create configuration.
In the Configuration section at the bottom of the page, for Configuration name, enter a unique name that describes the configuration. The name is the primary identifier for the configuration. The maximum length allowed is 512 characters.
For Video content source, enter the URL prefix for the HLS master manifest or DASH manifest for this stream, minus the asset ID. For example, if the master manifest URL is http://origin-server.com/a/master.m3u8, you would enter http://origin-server.com/a/. Alternatively, you can enter a shorter prefix such as http://origin-server.com, but then you must include the /a/ in the asset ID in the player request for content. The maximum length is 512 characters.

Note
If your content origin uses HTTPS, its certificate must be from a well-known certificate authority. (It can't be a self-signed certificate.) Otherwise, AWS Elemental MediaTailor fails to connect to the content origin and can't serve manifests in response to player requests.
For Ad decision server, enter the URL for your ADS. This is either the URL with variables as described in Step 3: Configure ADS request URL and query parameters, or the static VAST URL that you are using for testing purposes. The maximum length is 25,000 characters.

Note
If your ADS uses HTTPS, its certificate must be from a well-known certificate authority. (It can't be a self-signed certificate.) The same is true for mezzanine ad URLs returned by the ADS. Otherwise, MediaTailor fails to retrieve and stitch ads into the manifests from the content origin.
(Optional as needed for DASH) For Location, choose DISABLED if you have CDN routing rules set up for accessing MediaTailor manifests and you are either using client-side reporting or your players support sticky HTTP redirects.

For more information about the Location feature, see DASH location feature.
(Optional) If your origin server produces single-period DASH manifests, choose DASH mpd manifest origin type, and then choose SINGLE_PERIOD. By default, MediaTailor handles DASH manifests as multi-period manifests. For more information, see Integrating an MPEG-DASH source.
Choose Create configuration.

AWS Elemental MediaTailor displays the new configuration on the Configurations page.

Step 5: Test the configuration

After you save the configuration, test the stream using a URL in the appropriate format for your streaming protocol:

Example: HLS


playback-endpoint/v1/master/hashed-account-id/origin-id/master.m3u8

Example: DASH


playback-endpoint/v1/dash/hashed-account-id/origin-id/manifest.mpd

Where:

playback-endpoint is the unique playback endpoint that AWS Elemental MediaTailor generated when the configuration was created.

Example
```
https://bdaaeb4bd9114c088964e4063f849065.mediatailor.us-east-1.amazonaws.com
```
hashed-account-id is your AWS account ID.

Example
```
AKIAIOSFODNN7EXAMPLE
```
origin-id is the name that you gave when creating the configuration.

Example
```
myOrigin
```
master.m3u8 or manifest.mpd 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: HLS


https://bdaaeb4bd9114c088964e4063f849065.mediatailor.us-east-1.amazonaws.com/v1/master/AKIAIOSFODNN7EXAMPLE/myOrigin/master.m3u8

Example: DASH


https://bdaaeb4bd9114c088964e4063f849065.mediatailor.us-east-1.amazonaws.com/v1/dash/AKIAIOSFODNN7EXAMPLE/myOrigin/manifest.mpd

You can test the stream using one of the following methods.

As shown in the preceding example, enter the URL in a standalone player.

Test the stream in your own player environment.

Step 6: Send the playback request to AWS Elemental MediaTailor

Configure the downstream player or CDN to send playback requests to the configuration's playback endpoint provided from AWS Elemental MediaTailor. Any player-defined dynamic variables that you used in the ADS request URL in Step 3: Configure ADS request URL and query parameters must be defined in the manifest request from the player.

Example

Assume your template ADS URL is the following.


https://my.ads.com/ad?output=vast&content_id=12345678&playerSession=[session.id]&cust_params=[player_params.cust_params]

Then define [player_params.cust_params] in the player request by prefacing the key-value pair with ads.. AWS Elemental MediaTailor passes parameters that aren't preceded with ads. to the origin server instead of the ADS.

The player request URL is some variation of the following HLS and DASH examples.


https://bdaaeb4bd9114c088964e4063f849065.mediatailor.us-east-1.amazonaws.com/v1/master/AKIAIOSFODNN7EXAMPLE/myOrigin/master.m3u8?ads.cust_params=viewerinfo


https://bdaaeb4bd9114c088964e4063f849065.mediatailor.us-east-1.amazonaws.com/v1/dash/AKIAIOSFODNN7EXAMPLE/myOrigin/manifest.mpd?ads.cust_params=viewerinfo

When AWS Elemental MediaTailor receives the player request, it defines the player variables based on the information in the request. The resulting ADS request URL is some variation of this.


https://my.ads.com/ad?output=vast&content_id=12345678&playerSession=<filled_in_session_id>&cust_params=viewerinfo

For more information about configuring key-value pairs to pass to the ADS, see Using dynamic ad variables in AWS Elemental MediaTailor.

Step 7 (optional): Monitor AWS Elemental MediaTailor activity

Use Amazon CloudWatch and Amazon CloudWatch Logs to track AWS Elemental MediaTailor activity, such as the counts of requests, errors, and ad avails filled.

If this is your first time using CloudWatch with AWS Elemental MediaTailor, create an AWS Identity and Access Management (IAM) role to allow communication between the services.

To allow AWS Elemental MediaTailor access to CloudWatch (console)

Open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane of the IAM console, choose Roles, and then choose Create role.
Choose the Another AWS account role type.
For Account ID, enter your AWS account ID.
Select Require external ID and enter midas. This option automatically adds a condition to the trust policy that allows the service to assume the role only if the request includes the correct sts:ExternalID.
Choose Next: Permissions.
Add a permissions policy that specifies what actions this role can complete. Select from one of the following options, and then choose Next: Review:
- CloudWatchLogsFullAccess to provide full access to Amazon CloudWatch Logs
- CloudWatchFullAccess to provide full access to Amazon CloudWatch
For Role name, enter MediaTailorLogger, and then choose Create role.
On the Roles page, select the role that you just created.

Edit the trust relationship to update the principal:

On the role's Summary page, choose the Trust relationship tab.
Choose Edit trust relationship.

In the policy document, change the principal to the AWS Elemental MediaTailor service. It should look like this.


"Principal": {
   "Service": "mediatailor.amazonaws.com"
},

The entire policy should read as follows.


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "mediatailor.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "Midas"
        }
      }
    }
  ]
}

Choose Update Trust Policy.

Step 8: Clean up

To avoid extraneous charges, delete all unnecessary configurations.

To delete a configuration (console)

On the AWS Elemental MediaTailor Configurations page, do one of the following:
- Choose the Configuration name for the configuration that you want to delete.
- In the Configuration name column, choose the radio button, and then choose Delete.
In the Delete configuration confirmation box, enter Delete, and then choose Delete again.

AWS Elemental MediaTailor removes the configuration.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Getting started with MediaTailor

Getting started with MediaTailor channel assembly