AWS mediatailor: Document manifest.* and aws.* namespaces for pre-session hooks
Summary
Expands the PRE_SESSION_INITIALIZATION function output table to add the `manifest.*` and `aws.*` namespaces, explains how each value is applied (session persistence, manifest/segment/origin URLs, session-level service variables), states that function-written values take precedence over player-supplied query parameters of the same name, documents key/character validation rules, and updates the failure-behavior note to include manifest parameters and service variables.
Security assessment
The change is feature documentation for a new hook output namespace rather than a fix or advisory. It does describe security-relevant mechanics: function output can override player-supplied query parameters, and `manifest.*` values are appended to manifest, segment, and origin request URLs (potentially affecting origin/CDN behavior), with key segments restricted to letters, digits, and underscores and unknown `aws.*` keys rejected at function create/update time. These are behavioral constraints, not a documented vulnerability, and no CVE or incident is referenced.
Evidence
For the `player_params.*`, `manifest.*`, and `aws.*` namespaces, a value written by the function takes precedence over a player-supplied query parameter with the same name. Values the function does not set are unchanged.
Diff
diff --git a/mediatailor/latest/ug/monetization-functions-hooks-pre-session.md b/mediatailor/latest/ug/monetization-functions-hooks-pre-session.md index 0686a1218..e67cdb4e0 100644 --- a//mediatailor/latest/ug/monetization-functions-hooks-pre-session.md +++ b//mediatailor/latest/ug/monetization-functions-hooks-pre-session.md @@ -21,3 +21,9 @@ MediaTailor runs the function mapped to `PRE_SESSION_INITIALIZATION` once, at th -Namespace | Accepted types ----|--- -`player_params.*` | Strings, numbers, booleans +Namespace | Accepted types | How the output is used +---|---|--- +`player_params.*` | Strings, numbers, booleans | Persisted to the session as player parameters. See Player parameters (player_params.*). +`manifest.*` | Strings | Persisted to the session as manifest query parameters and applied to manifest, segment, and origin request URLs for the lifetime of the session. See Manifest query parameters (manifest.*). +`aws.*` | Strings | Sets MediaTailor service variables that control session-level behavior, such as `aws.startTime` and `aws.preroll`. Only the parameters listed in Service variables (aws.*) are accepted. + +For the `player_params.*`, `manifest.*`, and `aws.*` namespaces, a value written by the function takes precedence over a player-supplied query parameter with the same name. Values the function does not set are unchanged. + +### Player parameters (player_params.*) @@ -39,0 +46,25 @@ The total serialized size of all `player_params` output keys and values must not +### Manifest query parameters (manifest.*) + +Writing `manifest.`name`` in the function output has the same effect as the player including `manifest.`name`=`value`` as a query parameter on the session initialization request. MediaTailor removes the `manifest.` prefix and appends ``name`=`value`` to the manifest and segment URLs it generates for the session. MediaTailor also appends it to the manifest requests it makes to your content origin. For the full list of URLs that receive manifest query parameters, see [MediaTailor manifest query parameters](./manifest-query-parameters.html). + +Use this namespace for a value that must reach your content origin or content delivery network (CDN). This is useful when the value is computed at session start rather than supplied by the player. For example, a function can read a player-supplied `player_params.zip` and write `manifest.aws.mediatailor.channel.audienceId` so that an MediaTailor channel assembly origin receives `?aws.mediatailor.channel.audienceId=`value`` on every manifest request. For a complete example, see [Example 5: Origin audience routing](./monetization-functions-examples-origin-routing.html). + +The part of the key after `manifest.` must consist of one or more segments of letters, digits, and underscores separated by periods (for example, `manifest.token` or `manifest.aws.mediatailor.channel.audienceId`). Other characters are rejected when you create or update the function. Values are subject to the same character rules as player-supplied manifest query parameters; see [MediaTailor parameter character restrictions and URL-encoding](./manifest-query-parameters-character-restrictions.html). + +### Service variables (aws.*) + +The function can set the same `aws.*` service variables that a player can supply as query parameters at session initialization. MediaTailor applies the function's value before it constructs the session, so the value affects the entire session exactly as the equivalent query parameter would. The following parameters are accepted: + + * `aws.startTime`, `aws.preroll`, `aws.overlayAvails`, `aws.logMode`, `aws.availSuppressionMode`, `aws.availSuppressionValue`, and `aws.availSuppressionFillPolicy`. For values and behavior, see [MediaTailor service variables for session control](./variables-service.html). + + * `aws.insertionMode`, `aws.reportingMode`, and `aws.guidedPrefetchMode`. For values and behavior, see [MediaTailor server-guided ad insertion overview and implementation](./server-guided.html) and [MediaTailor server-side ad tracking and reporting](./ad-reporting-server-side.html). + + * `aws.adSignalingEnabled`. See [Ad ID decoration](./ad-id-decoration.html). + + * `aws.streamId`. See [Prefetching ads](./prefetching-ads.html). + + + + +Values are strings and must use the same format as the corresponding query parameter (for example, `"aws.preroll": "disabled"`). If a value cannot be parsed, MediaTailor ignores that parameter and keeps the session's existing value; the rest of the function output is still applied. Keys outside this list are rejected when you create or update the function. + @@ -49,0 +81,4 @@ The total serialized size of all `player_params` output keys and values must not + * Compute a manifest query parameter from player input, such as mapping a viewer's postal code to an audience identifier that your content origin or CDN reads on every manifest request. + + * Set session-level service variables, such as disabling pre-roll for returning viewers or choosing a start time, without requiring the player to send the corresponding `aws.*` query parameters. + @@ -55 +90 @@ The total serialized size of all `player_params` output keys and values must not -If a function attached to `PRE_SESSION_INITIALIZATION` fails for any reason, MediaTailor discards the function's output and proceeds as if no function were attached. The session starts normally without the function's player parameter values. +If a function attached to `PRE_SESSION_INITIALIZATION` fails for any reason, MediaTailor discards the function's output and proceeds as if no function were attached. The session starts normally without the function's player parameter, manifest query parameter, and service variable values. The session uses only what the player supplied at session initialization.