AWS mediatailor documentation change
Summary
Added guidance on handling player variables in prefetch schedules, clarified avail matching criteria requirements, restructured instructions for single/recurring prefetch types, and expanded retrieval/consumption configuration details.
Security assessment
The change adds security-relevant documentation by explicitly advising against defining player variables as dynamic variables in prefetch configurations, which could prevent misconfiguration-related vulnerabilities. However, there is no evidence this addresses an active security vulnerability.
Diff
diff --git a/mediatailor/latest/ug/creating-prefetch-schedules.md b/mediatailor/latest/ug/creating-prefetch-schedules.md index df4fc3550..9dbdd12e6 100644 --- a//mediatailor/latest/ug/creating-prefetch-schedules.md +++ b//mediatailor/latest/ug/creating-prefetch-schedules.md @@ -5,2 +4,0 @@ -Determining how often your client should call the CreatePrefetchSchedule API - @@ -13 +11,11 @@ The following procedure explains how to create a prefetch schedule by using the -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.html), 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](./getting-started-ad-insertion.html#getting-started-configure-request) in the _Getting started with MediaTailor_ ad insertion topic. +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.html), 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.html#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. @@ -27 +35 @@ If you want to use avail matching criteria in a schedule, make sure that you fir - * 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 **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. @@ -42 +50,12 @@ 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 session variables to include in the request to the ADS, if any. + 5. 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. + + + + +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. @@ -47,0 +67,2 @@ Show moreShow less + * 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.html#avail-matching-criteria-retr). + @@ -58 +79 @@ Show moreShow less - 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. + 2. 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. @@ -64 +85 @@ Show moreShow less - * In the [Avail matching criteria](./variables.html) 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](./understanding-prefetching.html#avail-matching-criteria). + * In the [Avail matching criteria](./variables.html) 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.html#avail-matching-criteria). @@ -66 +87 @@ Show moreShow less - 7. Select **Add avail criteria**. + 3. Select **Add avail criteria**. @@ -73 +94 @@ Prefetch schedules automatically expire after the consumption window's end time. -## Determining how often your client should call the CreatePrefetchSchedule API +### Determining how often your client should call the CreatePrefetchSchedule API @@ -76,0 +98,33 @@ Your client can programmatically call the [CreatePrefetchSchedule](https://docs. +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. + + * 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.html#avail-matching-criteria-recurring-retr) + + * In the [Dynamic variables](./variables.html) 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.html#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 [Using session variables](./variables-session.html). + + * For **Value** , enter a dynamic variable value, such as `my-event`. + + * To add another dynamic variable, choose Select **Add dynamic variable**. + + 2. 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.html) 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.html#avail-matching-criteria-recur). + + 3. 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.html) section. +