AWS mediatailor documentation change
Summary
Complete restructuring of dynamic variables documentation with updated terminology, added configuration aliases section, reorganization of content types, and conversion of implementation steps into topic links
Security assessment
The changes are organizational/structural improvements to documentation without any mention of security vulnerabilities, mitigations, or new security features. The addition of configuration aliases appears to be a documentation feature rather than a security control.
Diff
diff --git a/mediatailor/latest/ug/variables.md b/mediatailor/latest/ug/variables.md index 1225c284d..92696eaff 100644 --- a//mediatailor/latest/ug/variables.md +++ b//mediatailor/latest/ug/variables.md @@ -5 +5 @@ -Passing parameters to the ADS +# MediaTailor dynamic ad variables for ADS requests @@ -7 +7 @@ Passing parameters to the ADS -# Using dynamic ad variables in MediaTailor +AWS Elemental MediaTailor uses dynamic ad variables to pass information from your viewing session to the ad decision server (ADS). This information helps the ADS select the most relevant ads for your viewers. @@ -9 +9 @@ Passing parameters to the ADS -The AWS Elemental MediaTailor request to the ad decision server (ADS) includes information about the current viewing session, which helps the ADS choose the best ads to provide in its response. When you configure the ADS template in your MediaTailor configuration, you can include dynamic variables, also known as macros. Dynamic variables are replaceable strings. +This section provides an overview of dynamic ad variables and links to specific implementation guides. For step-by-step configuration instructions, see the individual topics below. @@ -11 +11 @@ The AWS Elemental MediaTailor request to the ad decision server (ADS) includes i -Dynamic variables can take the following forms: +###### Dynamic variable types @@ -13 +13 @@ Dynamic variables can take the following forms: - * **Static values** – Values that don't change from one session to the next. For example, the response type that MediaTailor expects from the ADS. +MediaTailor supports four types of dynamic variables: @@ -15 +15 @@ Dynamic variables can take the following forms: - * **Domain variables** – Dynamic variables that can be used for URL domains, such as the **my-ads-server.com** part of the URL http://my-ads-server.com. For details, see [Using domain variables](./variables-domains.html). + * **Session variables** – Automatically generated values like session ID and SCTE-35 data. See [MediaTailor session variables for ADS requests](./variables-session.html). @@ -17 +17 @@ Dynamic variables can take the following forms: - * **Session data** – Dynamic values that are provided by MediaTailor for each session, for example, the session ID. For details, see [Using session variables](./variables-session.html). + * **Player variables** – Custom parameters sent by your video player. See [MediaTailor player variables for ADS requests](./variables-player.html). @@ -19 +19 @@ Dynamic variables can take the following forms: - * **Player data** – Dynamic values that are provided by the player for each session. These describe the content viewer and help the ADS to determine which ads MediaTailor should stitch into the stream. For details, see [Using player variables](./variables-player.html). + * **Domain variables** – Dynamic URL domains for multi-origin configurations. See [Domain variables](./variables-domains.html). @@ -20,0 +21 @@ Dynamic variables can take the following forms: + * **Configuration aliases** – Predefined mappings for dynamic variable replacement. See [Configuration aliases](./configuration-aliases-comprehensive.html). @@ -24 +24,0 @@ Dynamic variables can take the following forms: -## Passing parameters to the ADS @@ -26 +26 @@ Dynamic variables can take the following forms: -The following steps describe how to set up dynamic variables in MediaTailor requests to the ADS. +###### Common use cases @@ -28 +28 @@ The following steps describe how to set up dynamic variables in MediaTailor requ - * For information about supported formatting for query parameters, see Manifest query parameter supported characters and limitations and ADS query parameter length limitations. +Use dynamic ad variables to: @@ -30 +30 @@ The following steps describe how to set up dynamic variables in MediaTailor requ - * For additional customizations to the ADS request, see Advanced usage. + * Pass viewer demographics and preferences to your ADS @@ -31,0 +32 @@ The following steps describe how to set up dynamic variables in MediaTailor requ + * Route requests to different origins based on geographic location @@ -32,0 +34 @@ The following steps describe how to set up dynamic variables in MediaTailor requ + * Enable time-shifted viewing with MediaPackage integration @@ -33,0 +36 @@ The following steps describe how to set up dynamic variables in MediaTailor requ + * Implement A/B testing and failover scenarios @@ -35 +37,0 @@ The following steps describe how to set up dynamic variables in MediaTailor requ -###### To pass session and player information to the ADS @@ -37 +38,0 @@ The following steps describe how to set up dynamic variables in MediaTailor requ - 1. Work with the ADS to determine the information that it needs so that it can respond to an ad query from AWS Elemental MediaTailor. @@ -39 +39,0 @@ The following steps describe how to set up dynamic variables in MediaTailor requ - 2. Create a configuration in MediaTailor that uses a template ADS request URL that satisfies the ADS requirements. In the URL, include static parameters and include placeholders for dynamic parameters. Enter your template URL in the configuration's **Ad decision server** field. @@ -41 +41 @@ The following steps describe how to set up dynamic variables in MediaTailor requ -In the following example template URL, `correlation` provides session data, and `deviceType` provides player data: +The following sections provide additional detail about using dynamic ad variables with MediaTailor. @@ -43,113 +43 @@ In the following example template URL, `correlation` provides session data, and - https://my.ads.server.com/path?correlation=[session.id]&deviceType=[player_params.deviceType] - - 3. On the player, configure the session initiation request for AWS Elemental MediaTailor to provide parameters for the player data. Include your parameters in the session initiation request, and omit them from subsequent requests for the session. - -The type of call that the player makes to initialize the session determines whether the player (client) or MediaTailor (server) provides ad-tracking reporting for the session. For information about these two options, see [Reporting ad tracking data ](./ad-reporting.html). - -Make one of the following types of calls, depending on whether you want server- or client-side ad-tracking reporting. In both of the example calls, `userID` is intended for the ADS and `auth_token` is intended for the origin: - - * (Option) Call for server-side ad-tracking reporting – Prefix the parameters that you want MediaTailor to send to the ADS with `ads`. Leave the prefix off for parameters that you want MediaTailor to send to the origin server: - -The following examples show incoming requests for HLS and DASH to AWS Elemental MediaTailor. MediaTailor uses the `deviceType` in its request to the ADS and the `auth_token` in its request to the origin server. - -HLS example: - - GET master.m3u8?ads.deviceType=ipad&auth_token=kjhdsaf7gh - -DASH example: - - GET manifest.mpd?ads.deviceType=ipad&auth_token=kjhdsaf7gh - - * (Option) Call for client-side ad-tracking reporting – Provide parameters for the ADS inside an `adsParams` object. - -HLS example: - - POST master.m3u8 - { - "adsParams": { - "deviceType": "ipad" - } - } - -DASH example: - - POST manifest.mpd - { - "adsParams": { - "deviceType": "ipad" - } - } - - - - -When the player initiates a session, AWS Elemental MediaTailor replaces the variables in the template ADS request URL with the session data and the player's `ads` parameters. It passes the remaining parameters from the player to the origin server. - -###### Example MediaTailor requests with ad variables - -The following examples show the calls to the ADS and origin server from AWS Elemental MediaTailor that correspond to the preceding player's session initialization call examples: - - * MediaTailor calls the ADS with session data and the player's device type: - - https://my.ads.server.com/path?correlation=896976764&deviceType=ipad - - * MediaTailor calls the origin server with the player's authorization token. - - * HLS example: - - https://my.origin.server.com/master.m3u8?auth_token=kjhdsaf7gh - - * DASH example: - - https://my.origin.server.com/manifest.mpd?auth_token=kjhdsaf7gh - - - - -### Manifest query parameter supported characters and limitations - -You can use the following characters in query parameters that are used in manifest requests: - - * Alphanumeric (A-Z, a-z, 0-9) - - * Periods (.) - - * Hyphens (-) - - * Underscores (_) - - * Back slashes (\\) - - - - -###### Length limitations - -The total length of all manifest query parameters (the key and value combined) must not exceed 2000 characters. - -###### Unsupported characters - -You can't use the following characters in manifest query parameters: `:` `?` `&` `=` `%` `/` (forward slash) - -### ADS query parameter length limitations - -The following length limitations apply to query parameters that are use in requests to the ADS: - - * **ADS parameter name** : 10000 characters - - * **ADS parameter value** : 25000 characters - - * **ADS URL** : 25000 characters - - - - -### Advanced usage - -You can customize the ADS request in many ways with player and session data. The only requirement is to include the ADS host name. - -The following examples show some of the ways that you can customize your request: - - * Concatenate player parameters and session parameters to create new parameters. Example: - - https://my.ads.com?key1=[player_params.value1][session.id] +###### Topics @@ -157 +45 @@ The following examples show some of the ways that you can customize your request - * Use a player parameter as part of a path element. Example: + * [Session variables](./variables-session.html) @@ -159 +47 @@ The following examples show some of the ways that you can customize your request - https://my.ads.com/[player_params.path]?key=value + * [Player variables](./variables-player.html) @@ -161 +49 @@ The following examples show some of the ways that you can customize your request - * Use player parameters to pass both path elements and the keys themselves, rather than just values. Example: + * [Domain variables](./variables-domains.html) @@ -163 +51 @@ The following examples show some of the ways that you can customize your request - https://my.ads.com/[player_params.path]?[player_params.key1]=[player_params.value1] + * [Passing ADS parameters](./passing-paramters-to-the-ads.html) @@ -164,0 +53 @@ The following examples show some of the ways that you can customize your request + * [Configuration aliases](./configuration-aliases-comprehensive.html) @@ -165,0 +55 @@ The following examples show some of the ways that you can customize your request + * [Parameter routing](./parameter-routing-behavior.html) @@ -166,0 +57 @@ The following examples show some of the ways that you can customize your request + * [MediaPackage integration](./mediapackage-integration-param.html) @@ -168 +59 @@ The following examples show some of the ways that you can customize your request -For more information about using dynamic domain, session, and player variables, select the applicable topic. + * [Session behavior](./parameter-session-behavior.html) @@ -170 +61 @@ For more information about using dynamic domain, session, and player variables, -###### Topics + * [Parameter reference](./parameter-comprehensive-reference.html) @@ -172 +63 @@ For more information about using dynamic domain, session, and player variables, - * [Using domain variables](./variables-domains.html) + * [Parameter troubleshooting](./parameter-troubleshooting.html) @@ -174 +65 @@ For more information about using dynamic domain, session, and player variables, - * [Using session variables](./variables-session.html)