Creating prefetch schedules - AWS Elemental MediaTailor
Determining how often your client should call the CreatePrefetchSchedule API

Creating prefetch schedules

The following procedure explains how to create a prefetch schedule by using the MediaTailor console. For information about creating and managing prefetch schedules programmatically using the MediaTailor API, see PrefetchSchedules in the AWS Elemental MediaTailor API Reference.

Note

If you want to use avail matching criteria in a schedule, make sure that you first configure your playback configuration's ADS URL template with dynamic variables, otherwise the avail matching criteria won't have an effect. For information about working with dynamic variables, see Step 3: Configure ADS request URL and query parameters in the Getting started with MediaTailor ad insertion topic.

To create a new prefetch schedule using the console

  1. Open the MediaTailor console at https://console.aws.amazon.com/mediatailor/.

  2. In the navigation pane, choose Configurations. Select the playback configuration that you want to create a prefetch schedule for.

  3. On the Prefetch schedules tab, choose Add prefetch schedule.

  4. Under the Prefetch schedule details pane, do the following:

    • For Name, enter an identifier for your prefetch schedule, such as my-prefetch-schedule.

    • For Stream ID, optionally enter a unique ID. If your origin contains multiple playback streams, you can use this ID to instruct MediaTailor to place ads in a specific stream. For example, if your origin has a sports stream and a TV show stream, you can use the stream ID to create prefetch schedules to insert ads targeted for the sports stream. You pass the stream ID value to MediaTailor in your client's session initialization or manifest request. For more information see the following example.

      • For server-side tracking, include the ?aws.streamId query parameter and value in your client's GET HTTP request to your MediaTailor endpoint. For general information about server-side tracking see Server-side ad tracking. A manifest request to an HLS endpoint that includes a stream ID looks like the following, where myStreamId is the name of your stream ID:

        GET <mediatailorURL>/v1/master/<hashed-account-id>/<origin-id>/<asset-id>?aws.streamId=myStreamId

      • For client-side tracking, include the streamId key and value in your client's POST HTTP session initialization request body to the MediaTailor/v1/session endpoint. For general information about client-side tracking see Client-side ad tracking. A session initialization request that includes a stream ID looks like the following, where myStreamId is the name of your stream ID:

        POST <mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>
{
    'streamId': 'myStreamId'
}
      Show moreShow less

  5. On the Retrieval pane, specify the retrieval settings you want to use. These settings determine when MediaTailor prefetches ads from the ADS. They also determine which dynamic variables to include in the request to the ADS, if any.

    • For Start time, enter the time when MediaTailor can start prefetch retrievals for this ad break. MediaTailor will attempt to prefetch ads for manifest requests made by your client on or after this time. The default value is the current time. If you don't specify a value, the service starts prefetch retrieval as soon as possible.

    • For End time, enter the time when you want MediaTailor to stop prefetching ads for this ad break. MediaTailor will attempt to prefetch ads for manifest requests that occur at or before this time. The retrieval window can overlap with the consumption window.

    • In the Dynamic variables section, enter as many as 100 dynamic variables. MediaTailor uses these variables for substitution in prefetch requests that it sends to the ADS. If you don't enter any dynamic variables, MediaTailor makes a best effort attempt to interpolate the values for the dynamic variables contained in your ADS URL.

      • Select Add dynamic variable.

      • For Key, enter a dynamic variable key, such as scte.event_id. You can use any dynamic variable that MediaTailor supports. For information about dynamic variables, see Using dynamic ad variables in MediaTailor.

      • For Value, enter a dynamic variable value, such as my-event.

      • To add another dynamic variable, choose Select Add dynamic variable.

  6. On the Consumption pane, specify the settings that you want to use for the consumption window. These settings determine when MediaTailor places the ads into the ad break. They also determine any avail matching criteria that you want to use.

    • For Start time, enter the time when you want MediaTailor to begin to place prefetched ads into the ad break. the default value is the current time. If you don't specify a time, the service starts prefetch consumption as soon as possible.

    • For End time, enter a time when you want MediaTailor to stop placing the prefetched ads into the ad break. MediaTailor will attempt to prefetch ads for your client's manifest requests that occur at or before this time. The end time must be after the start time, and less than one day from now. The consumption window can overlap with the retrieval window.

    • In the Avail matching criteria section, select Add avail criteria and add as many ad five avail matching criteria to your schedule. Then, under Dynamic variable key, add a dynamic variable key, such as scte.event_id. MediaTailor will place the prefetched ads into the ad break only if it meets the criteria defined by the dynamic variable values that either your client passes to MediaTailor, or that MediaTailor infers from information such as session data. For information, see the preceding section avail-matching-criteria.

  7. Select Add avail criteria.

Prefetch schedules automatically expire after the consumption window's end time. For diagnostic purposes, they remain visible for at least 7 days, after which MediaTailor automatically deletes them. Alternatively, you can manually delete a prefetch schedule at any time. For information about how to manually delete a prefetch schedule, see the following Deleting prefetch schedules section.

Determining how often your client should call the CreatePrefetchSchedule API

Your client can programmatically call the CreatePrefetchSchedule API once per day to set up retrieval and consumption if you have knowledge of exactly when ad breaks will occur. Or, your client can call the API many times over the course of the day to define retrieval and consumption. When choosing an API call frequency, take into consideration MediaTailor's maximum number of active prefetch schedules, and the likelihood of whether your ad break schedule will change after you create your prefetch schedule(s). If it's likely that the ad break schedule will change after you've created your prefetch schedule(s), you might want to call the API more frequently.