# Prefetching ads Added recurring prefetch Updated sections to include information about recurring prefetch schedules.Prefetching ads topic MediaTailor can now prefetch ads for ad breaks before they occur. Use AWS Elemental MediaTailor ad prefetching for live streams to help reduce peak load on ad decision servers (ADS) and decrease manifest delivery latency at the start of each ad break. When you define a prefetch schedule, MediaTailor follows the schedule to retrieve ads from the ADS and prepare them for ad insertion before they’re needed for an ad break. During live streams, prefetching can help mitigate decreased ad fill rates and missed monetization opportunities because of ad request and transcoding timeouts or other network delays. **Note** Ad prefetching does not work with server-guided ad insertion (SGAI) methods, including traditional server-guided and HLS Interstitials. SGAI methods do not require prefetching because players only fetch ads they are going to play, and manifests can be served by CDNs without MediaTailor seeing individual session requests. To set up ad prefetching, you create one or more *prefetch schedules* on your playback configuration. A prefetch schedule tells MediaTailor how and when to retrieve and prepare ads for an upcoming ad break. + If an event has ad avails that are on a predictable schedule, use a *single prefetch schedule*. Each single prefetch schedule defines a single set of ads for MediaTailor to place in a single ad avail. To prefetch ads for multiple ad avails when you use single prefetch schedules, you must create multiple prefetch schedules (up to 24 hours before the ad avail) that correlate to each ad avail. + If an event has ad avails that aren't on a predictable schedule, use a *recurring prefetch schedule*. A recurring prefetch schedule automatically creates a schedule and prefetches ads before each ad break in an event. The recurring prefetch schedule retrieves ads for every ad avail within a defined period of time (up to 24 hours before the event ends). You don’t need to create a schedule for each ad avail, but you do lose some of the timing control that single prefetch offers. The following topics describe more about ad prefetching. **Topics** + [ # How prefetching works ](understanding-prefetching.md) + [ # Creating prefetch schedules ](creating-prefetch-schedules.md) + [ # TPS-based traffic shaping ](tps-traffic-shaping.md) + [ # Deleting prefetch schedules ](deleting-prefetch-schedules.md) # How prefetching works When your client makes a manifest request to MediaTailor, the service evaluates all of the prefetch schedules that are associated with the playback configuration. If MediaTailor doesn't find a matching prefetch schedule, the service reverts to normal ad insertion and doesn't prefetch ads. If MediaTailor finds a matching prefetch schedule, the service evaluates the schedule based on two components: retrieval and consumption. The configuration of each component varies between single prefetch schedules and recurring prefetch schedules, as described in the following sections. ## Single prefetch schedule flow **Retrieval** This defines the *retrieval window*, which is the time range when MediaTailor prefetches ads from the ADS. Be sure to schedule this window for a time that's before the ad break. The following provides an overview of how MediaTailor processes a single prefetch schedule. For steps to create a single prefetch schedule in the console, see [Creating prefetch schedules](creating-prefetch-schedules.md). For API instruction, see [PrefetchSchedules](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_PrefetchSchedule.html) in the *AWS Elemental MediaTailor API Reference*. During the specified *retrieval window*, MediaTailor sends requests to the ADS to retrieve and prepare ads for later insertion in playback sessions. + MediaTailor optionally uses traffic shaping to limit the number of requests to the ADS at one time. You can choose between two approaches: *Time-window traffic shaping* - MediaTailor spreads requests across the specified number of seconds instead of sending requests for all sessions at one time. This dispersed traffic distribution helps to prevent the ADS from becoming overwhelmed, resulting in time outs and low ad fill rates. *TPS-based traffic shaping* - MediaTailor limits requests based on transactions per second (TPS) and concurrent users. This approach provides more intuitive configuration based on your ADS capacity limits. For more information, see [TPS-based traffic shaping](tps-traffic-shaping.md). + If you set up *dynamic variables*, MediaTailor includes these variables in the requests to the ADS. MediaTailor uses these variables to match ad avails to prefetch schedules during the consumption window. See the following *Consumption* section for more information. **Example** A live event lasts from 7:45AM to 10AM, with an ad break at 8:15AM. You configure MediaTailor to retrieve ads from 7:45AM to 8AM, with a traffic shaping window of 60 seconds. With 500,000 concurrent users, MediaTailor distributes the ADS requests to achieve an average rate of approximately 8,333 transactions per second for 60 seconds (500,000 users/60 seconds=8,333 requests per second), instead of sending all requests simultaneously. The retrieval configuration includes the dynamic variable key `scte.event` and value `1234`. MediaTailor includes this variable in the requests to the ADS, which then can be used to target specific advertisers to the event ID 1234. **Consumption** When MediaTailor encounters SCTE-35 ad break markers during the consumption window, it places the prefetched ads in an ad break. + If you didn’t set avail matching criteria, MediaTailor inserts ads in the first break in the consumption window. + If you did set a *dynamic variable key* for *avail* *matching* *criteria*, MediaTailor evaluates these criteria against the dynamic variables that you set in the retrieval window. An ad break is eligible for prefetched ad insertion only if the avail matching criteria are met. MediaTailor inserts ads in the first break that meets the criteria. For a list of supported avail-matching criteria, see the *Available for ad prefetch* column in the table on [MediaTailor session variables for ADS requests](variables-session.md). **Example continued** You set the start time for consumption as 8:15AM, and the end time as 8:17AM. You include `scte.event_id` for the key in the avail matching criteria. For each ad break that MediaTailor encounters from 8:15AM to 8:17AM, it evaluates the SCTE event ID for each ad break. In each playback session, MediaTailor inserts the prefetched ads in the first ad break that has an event ID of 1234 (as defined in the retrieval dynamic variables). For ad breaks that don’t contain the correct event ID, MediaTailor performs standard ad insertion. ## Recurring prefetch schedule flow **Retrieval** This defines the *recurring retrieval window*, which is the time range when MediaTailor prefetches and inserts ads for a live event (up to 24 hours). The following provides an overview of how MediaTailor processes recurring prefetch schedules. For steps to create a recurring prefetch schedule in the console, see [Creating prefetch schedules](creating-prefetch-schedules.md). For API instruction, see [PrefetchSchedules](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_PrefetchSchedule.html) in the *AWS Elemental MediaTailor API Reference*. During the specified recurring prefetch window, MediaTailor retrieves and inserts ads for a live event that’s up to 24 hours. After each ad break in the window, MediaTailor automatically retrieves ads for the next ad break. + If you set the *delay after avail end*, MediaTailor waits the specified time before retrieving the next set of ads for the next ad break. + MediaTailor optionally uses traffic shaping to limit the number of requests to the ADS at one time. You can choose between two approaches: *Time-window traffic shaping* - MediaTailor spreads requests across the specified number of seconds instead of sending requests for all sessions at one time. This dispersed traffic distribution helps to prevent the ADS from becoming overwhelmed, resulting in time outs and low ad fill rates. *TPS-based traffic shaping* - MediaTailor limits requests based on transactions per second (TPS) and concurrent users. This approach provides more intuitive configuration based on your ADS capacity limits. For more information, see [TPS-based traffic shaping](tps-traffic-shaping.md). + If you set up *dynamic variables*, MediaTailor includes these variables in the requests to the ADS. MediaTailor uses these variables to match ad avails to prefetch schedules during the consumption window. See the following *Consumption* section for more information. **Example** A live event lasts from 7PM to 8:45PM, with four ad breaks over that time. The ad breaks aren’t on a predictable schedule. You configure the recurring prefetch from 7PM to 8:45PM, with a 10 minute delay and traffic shaping window of 60 seconds. After each avail, MediaTailor retrieves ads for the next ad break. Ten minutes after the avail ends, MediaTailor starts to send retrieval requests to the ADS. With a 60-second traffic-shaping window and 500,000 concurrent users, MediaTailor distributes the ADS requests to achieve an average rate of approximately 8,333 transactions per second for 60 seconds (500,000 users/60 seconds=8,333 requests per second), instead of sending all requests simultaneously. The retrieval configuration includes the dynamic variable key `scte.event` and value `1234`. MediaTailor includes this variable in the requests to the ADS, which then can be used to target specific advertisers to the event ID 1234. **Consumption** When MediaTailor encounters SCTE-35 ad break markers, it places the prefetched ads in an ad break. + If you set the *retrieved ad expiration*, prefetched ads are available for insertion until the specified expiration. + If you didn’t set avail matching criteria, MediaTailor inserts ads in the first break in the consumption window. + If you did set a *dynamic variable key* for *avail* *matching* *criteria*, MediaTailor evaluates these criteria against the dynamic variables that you set in the retrieval window. An ad break is eligible for prefetched ad insertion only if the avail matching criteria are met. MediaTailor inserts ads in the first break that meets the criteria. For a list of supported avail-matching criteria, see the *Available for ad prefetch* column in the table on [MediaTailor session variables for ADS requests](variables-session.md). **Example continued** In the consumption, you include `scte.event_id` for the key in the avail matching criteria. For each ad break that MediaTailor encounters, it evaluates the SCTE event ID for each ad break. In each playback session, MediaTailor inserts the prefetched ads in each ad break that has an event ID of 1234 (as defined in the retrieval dynamic variables). For ad breaks that don’t contain the correct event ID, MediaTailor performs standard ad insertion. You set the ad expiration to 2700 seconds so retrieved ads are available for insertion for 45 minutes. The following graphic illustrates the example, with the small squares representing ad breaks. The recurring prefetch schedule settings are illustrated along the event timeline. ![\[Graphical illustration of a live event including recurring prefetch schedule configurations.\]](http://docs.aws.amazon.com/mediatailor/latest/ug/images/recurring_prefetch_timeline.png) ## Understanding prefetching costs There are no costs for making ad retrieval requests. However, for prefetch ad retrieval, you'll be charged at the standard transcoding rate for the prefetched ads that MediaTailor transcodes. For prefetch ad consumption, you'll be charged at the standard rate for ad insertion for the prefetched ads that MediaTailor places in ad breaks. For information about transcoding and ad insertion costs, see [AWS Elemental MediaTailor Pricing](https://aws.amazon.com/mediatailor/pricing/). # 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](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_PrefetchSchedule.html) in the *AWS Elemental MediaTailor API Reference*. **Note** When configuring prefetch schedules in MediaTailor, it's important to understand how different types of variables are handled. **Avail matching criteria** 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 session variables](variables-session.md), otherwise the avail matching criteria won't have an effect. For information about working with dynamic session variables, see [Step 3: Configure ADS request URL and query parameters](getting-started-ad-insertion.md#getting-started-configure-request) in the Getting started with MediaTailor ad insertion topic. **Player variables in prefetch schedules** When you create a prefetch schedule, don't define player variables as dynamic variables in your prefetch configuration. Instead, pass the player variables as you normally would at session start. MediaTailor automatically includes these variables in prefetch ad requests if the variables are mapped in the ADS template URL. **To create a new prefetch schedule using the console** 1. Open the MediaTailor console at [https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/). 1. In the navigation pane, choose **Configurations**. Select the playback configuration that you want to create a prefetch schedule for. 1. On the **Prefetch schedules** tab, choose **Add prefetch schedule**. 1. 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 playback configuration 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 [MediaTailor server-side ad tracking and reporting](ad-reporting-server-side.md). 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 /v1/master///?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](ad-reporting-client-side.md). A session initialization request that includes a stream ID looks like the following, where `myStreamId` is the name of your stream ID: ``` POST /v1/session/// { 'streamId': 'myStreamId', 'reportingMode': 'client' } ``` 1. For **Prefetch type**, make your selection and choose the corresponding section for assistance with additional fields: + Choose **Single** if you're creating one prefetch schedule for one ad break in an event. + Choose **Recurring** if you're creating a schedule that automatically prefetches ads before each ad break in an event. ## Single prefetch schedule To create a schedule that prefetches ads before one ad avail in an event. 1. 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 session 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. + Optionally, configure traffic shaping to limit the number of requests to the ADS at one time. Choose one of the following approaches: *Time-window approach*: For **Traffic shaping window duration**, enter the number of seconds that MediaTailor should distribute requests to the ADS. For more information, see [Single prefetch schedule retrieval explanation](understanding-prefetching.md#avail-matching-criteria-retr). *TPS-based approach*: Configure **Peak TPS** and **Peak concurrent users** to limit requests based on transactions per second and concurrent users. For more information, see [TPS-based traffic shaping](tps-traffic-shaping.md). + In the [**Dynamic variables**](variables.md) section, enter as many as 100 dynamic session variables. MediaTailor uses these variables for substitution in prefetch requests that it sends to the ADS. If you don't enter any dynamic session variables, MediaTailor makes a best effort attempt to interpolate the values for the dynamic variables contained in your [ADS](configurations-create.md#configurations-create-main) URL. + Select **Add dynamic variable**. + For **Key**, enter a dynamic session variable key, such as `scte.event_id`. You can use any dynamic variable that MediaTailor supports. For information about dynamic session variables, see [MediaTailor session variables for ADS requests](variables-session.md). + For **Value**, enter a dynamic variable value, such as *my-event*. + To add another dynamic variable, choose Select **Add dynamic variable**. 1. 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**](variables.md) 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. If an ad break doesn't meet the specified matching criteria, MediaTailor skips the prefetch for that break. For information, see the [Single prefetch schedule consumption explanation](understanding-prefetching.md#avail-matching-criteria). 1. 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](deleting-prefetch-schedules.md) section. ### Determining how often your client should call the CreatePrefetchSchedule API Your client can programmatically call the [CreatePrefetchSchedule](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_CreatePrefetchSchedule.html) 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 the [maximum number of active prefetch schedules](quotas.md#prefetch-schedules-limit), 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. ## Recurring prefetch schedule To create a schedule that prefetches ads before each ad avail in an event. 1. On the **Recurring 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 session variables to include in the request to the ADS, if any. + For **Recurring prefetch window**, 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 **Delay after avail end**, enter the number of seconds that MediaTailor should wait after an avail ends before prefetching ads for the next avail. If you don't specify a value, MediaTailor defaults to a no delay. + Optionally, configure traffic shaping to limit the number of requests to the ADS at one time. Choose one of the following approaches: *Time-window approach*: For **Traffic shaping window duration**, enter the number of seconds that MediaTailor should distribute requests to the ADS. For more information, see [Recurring prefetch schedule retrieval explanation](understanding-prefetching.md#avail-matching-criteria-recurring-retr) *TPS-based approach*: Configure **Peak TPS** and **Peak concurrent users** to limit requests based on transactions per second and concurrent users. For more information, see [TPS-based traffic shaping](tps-traffic-shaping.md). + In the [**Dynamic variables**](variables.md) section, enter as many as 100 dynamic session variables. MediaTailor uses these variables for substitution in prefetch requests that it sends to the ADS. If you don't enter any dynamic session variables, MediaTailor makes a best effort attempt to interpolate the values for the dynamic variables contained in your [ADS](configurations-create.md#configurations-create-main) URL. + Select **Add dynamic variable**. + For **Key**, enter a dynamic session variable key, such as `scte.event_id`. You can use any dynamic variable that MediaTailor supports. For information about dynamic session variables, see [MediaTailor session variables for ADS requests](variables-session.md). + For **Value**, enter a dynamic variable value, such as *my-event*. + To add another dynamic variable, choose Select **Add dynamic variable**. 1. 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 **Retrieved ad expiration**, indicate how long after retrieval ads are available for insertion. + In the [**Avail matching criteria**](variables.md) 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. If an ad break doesn't meet the specified matching criteria, MediaTailor skips the prefetch for that break. For information, see the [Recurring prefetch schedule consumption explanation](understanding-prefetching.md#avail-matching-criteria-recur). 1. 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](deleting-prefetch-schedules.md) section. # TPS-based traffic shaping Added TPS traffic shaping Updated sections to include information about limiting requests to the ADS based on TPS. AWS Elemental MediaTailor provides two optional traffic shaping approaches to limit the number of requests to the ADS at one time. TPS-based traffic shaping offers an alternative to time-window based traffic shaping for prefetch schedules. This approach provides more intuitive configuration by allowing you to specify your ad decision server (ADS) capacity in terms of transactions per second (TPS) and expected concurrent users, rather than time calculations. ## How TPS-based traffic shaping works Instead of specifying retrieval window durations, you provide the following parameters: Peak TPS The maximum number of requests per second that your ADS can handle. This parameter has no default value. Peak concurrent users The expected peak number of concurrent viewers for your content. This parameter has no default value. MediaTailor automatically distributes prefetch requests across time to stay within your specified TPS limit, regardless of the number of concurrent sessions. **Example TPS-based configuration example** Your ADS can handle 500 TPS, and you expect 100,000 concurrent viewers during peak times. You configure: + Peak TPS: 500 + Peak concurrent users: 100,000 MediaTailor automatically distributes prefetch requests across time to stay within your specified TPS limit, regardless of the number of concurrent sessions. # Deleting prefetch schedules The following procedure explains how to delete a prefetch schedule by using the MediaTailor console. For information about how to delete prefetch schedules programmatically using the MediaTailor API, see [DeletePrefetchSchedule](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_DeletePrefetchSchedule.html) in the *AWS Elemental MediaTailor API Reference*. **Note** Deletion doesn't occur in real time. You might experience a delay while MediaTailor deletes the prefetch schedule(s), during which time prefetch retrieval and consumption will continue to run in the background. **To delete a prefetch schedule using the console** 1. Open the MediaTailor console at [https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/). 1. In the navigation pane, choose **Configurations**. Select the playback configuration that contains the prefetch schedule(s) that you want to delete. 1. On the **Prefetch schedules** tab, select the prefetch schedule that you want to delete. Then, choose **Delete**.