AWS mediatailor documentation change
Summary
Restructured documentation to differentiate between single and recurring prefetch schedules, added traffic shaping explanations, dynamic variable usage examples, and cost clarification.
Security assessment
The changes focus on operational improvements (traffic shaping to prevent ADS overload) and feature clarification. While traffic shaping improves reliability, there is no evidence of addressing vulnerabilities, authentication, or data protection. Dynamic variables are used for ad targeting rather than security controls.
Diff
diff --git a/mediatailor/latest/ug/understanding-prefetching.md b/mediatailor/latest/ug/understanding-prefetching.md index b158e39ef..4104d367c 100644 --- a//mediatailor/latest/ug/understanding-prefetching.md +++ b//mediatailor/latest/ug/understanding-prefetching.md @@ -5 +5 @@ -Understanding prefetching costs +Single prefetch schedule flowRecurring prefetch schedule flowUnderstanding prefetching costs @@ -11 +11 @@ When your client makes a manifest request to MediaTailor, the service evaluates -If MediaTailor finds a matching prefetch schedule, the service evaluates the schedule based on two components, retrieval and consumption. +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. @@ -13 +13 @@ If MediaTailor finds a matching prefetch schedule, the service evaluates the sch -**Retrieval** +## Single prefetch schedule flow @@ -14,0 +15 @@ If MediaTailor finds a matching prefetch schedule, the service evaluates the sch +** @@ -16 +17 @@ If MediaTailor finds a matching prefetch schedule, the service evaluates the sch -This defines the _retrieval window_ , which is the time range when MediaTailor prefetches ads from the ADS. To set up the retrieval window, first determine when the ad break will occur. +Retrieval** @@ -18 +18,0 @@ This defines the _retrieval window_ , which is the time range when MediaTailor p -For advanced use cases, you can optionally add [dynamic variables](./variables.html) to the prefetch request that MediaTailor sends to the ADS. This lets you send session, player, and other data to the ADS as part of the request. If you don't include dynamic variables in the prefetch schedule, MediaTailor uses the dynamic variables, if any, that you configured in your playback configuration's ADS URL. @@ -20 +20 @@ For advanced use cases, you can optionally add [dynamic variables](./variables.h -**Consumption** +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. @@ -21,0 +22 @@ For advanced use cases, you can optionally add [dynamic variables](./variables.h +For steps to create a single prefetch schedule in the console, see [Creating prefetch schedules](./creating-prefetch-schedules.html). For API instruction, see [PrefetchSchedules](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_PrefetchSchedule.html) in the _AWS Elemental MediaTailor API Reference_. @@ -23 +24 @@ For advanced use cases, you can optionally add [dynamic variables](./variables.h -This defines the _consumption window_ , which is the time range when MediaTailor places prefetched ads into the ad break. +During the specified _retrieval window_ , MediaTailor sends requests to the ADS to retrieve and prepare ads for later insertion in playback sessions. @@ -25 +26,23 @@ This defines the _consumption window_ , which is the time range when MediaTailor -For this component, you can optionally add as many as five dynamic session variables for _avail matching criteria_ to a prefetch schedule. MediaTailor uses these criteria to determine whether the ad break is eligible for placement of the prefetched ads. For example, you can use the [scte.event_id](./variables.html) dynamic variable if you want the service to place ads in an ad break with a specific SCTE event ID. MediaTailor places the prefetched ads into an ad break only if the ad break meets the criteria defined by the dynamic session variables. + * If you set the _traffic shaping window_ , 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. + + * 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. @@ -29 +51,0 @@ For a list of supported avail-matching criteria, see the _Available for ad prefe -When your client sends manifest requests to MediaTailor during the retrieval window, MediaTailor proactively sends requests to the ADS to retrieve and prepare the ads for later insertion. If you set up dynamic variables for retrieval, MediaTailor includes those variables in the requests. @@ -31 +53,65 @@ When your client sends manifest requests to MediaTailor during the retrieval win -When MediaTailor encounters an SCTE-35 ad break marker during the consumption window, the service uses the avail matching criteria, if configured, to determine which ad break to place the ads in. If avail matching criteria aren't configured, MediaTailor places the prefetched ads in the first ad break within the consumption window. + + +###### 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.html). 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. + + * If you set the _traffic shaping window_ , 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. + + * 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 [Using session variables](./variables-session.html). + + + + +###### 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. + + @@ -35 +121 @@ When MediaTailor encounters an SCTE-35 ad break marker during the consumption wi -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/). +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/).