AWS mediatailor: Document inference.* contextual metadata variables for PRE_ADS_REQUEST
Summary
Adds documentation of read-only Elemental Inference contextual metadata variables (inference.enriched, feedId, dataEndpoint, pts, timescale, region, previousBreakEndPts, parseError) available at the PRE_ADS_REQUEST hook, plus minor wording/link fixes.
Security assessment
The change documents new read-only input variables for ad-request functions and how to use them for contextual ad targeting. It is functional/feature documentation with no mention of a vulnerability, credential handling, or access-control change, so it is not security documentation.
Evidence
+`inference.region` | String | The AWS Region extracted from the query URL. Use this as the `TargetRegion` for your `AWS_SERVICE_REQUEST` function.
Diff
diff --git a/mediatailor/latest/ug/monetization-functions-hooks-pre-ads.md b/mediatailor/latest/ug/monetization-functions-hooks-pre-ads.md index 429659de7..fa3b9a994 100644 --- a//mediatailor/latest/ug/monetization-functions-hooks-pre-ads.md +++ b//mediatailor/latest/ug/monetization-functions-hooks-pre-ads.md @@ -7 +7 @@ -When it firesInputOutput namespace allowedTypical use casesFailure behavior +When it firesInputElemental Inference contextual metadata variables (inference.*)Output namespace allowedTypical use casesFailure behavior @@ -17 +17,26 @@ MediaTailor runs the function mapped to `PRE_ADS_REQUEST` once per ad break, imm -All fields from `PRE_SESSION_INITIALIZATION`, plus `avail.*`, `scte.*`, `asset.*`, and `adsRequest.*` (url, method, headers, body). For all available fields, see [Input field reference](./monetization-functions-hooks.html#monetization-functions-hooks-input-ref). +All fields from `PRE_SESSION_INITIALIZATION`, plus `avail.*`, `scte.*`, `asset.*`, `inference.*`, and `adsRequest.*` (url, method, headers, body). For all available fields, see [Input field reference](./monetization-functions-hooks.html#monetization-functions-hooks-input-ref). + +## Elemental Inference contextual metadata variables (inference.*) + +When your upstream encoder (such as AWS Elemental MediaLive) is configured for contextual metadata enrichment, it embeds Elemental Inference query parameters in SCTE-35 ad break markers. MediaTailor automatically parses these markers and exposes the following read-only variables in the `inference` namespace. These variables are the primary mechanism for dynamically configuring `AWS_SERVICE_REQUEST` functions that call Elemental Inference. + +###### Note + +The `inference.*` variables are available only at the `PRE_ADS_REQUEST` hook. They are not available at `PRE_SESSION_INITIALIZATION`. + +Field | Type | Description +---|---|--- +`inference.enriched` | Boolean | `true` if Elemental Inference data was found and parsed successfully from the SCTE-35 marker. Check this before using other `inference.*` fields. +`inference.feedId` | String | The Elemental Inference feed identifier. +`inference.dataEndpoint` | String | The data endpoint URL prefix for the Elemental Inference feed. Use this to construct the full GetMetadata URL. +`inference.pts` | Long | The presentation timestamp (PTS) corresponding to the ad break signal. Used as the end of the query time window. +`inference.timescale` | Long | The timescale for interpreting PTS values (for example, 90000 for 90 kHz). +`inference.region` | String | The AWS Region extracted from the query URL. Use this as the `TargetRegion` for your `AWS_SERVICE_REQUEST` function. +`inference.previousBreakEndPts` | Long | The PTS at which content resumed after the previous ad break. Use this as the start of the query time window to analyze only the content that played between breaks. Absent for the first ad break in a session. +`inference.parseError` | Boolean | `true` if an Elemental Inference marker was found but could not be parsed. Indicates a configuration issue with the upstream encoder. + +These variables are read-only. Functions cannot modify `inference.*` values. + +When `inference.enriched` is `false` or absent, the remaining `inference.*` fields are not available. Your JSONata expressions must include fallback values to handle this case gracefully. + +For how to use these variables in practice, see [Elemental Inference integration](./monetization-functions-elemental-inference-integration.html). @@ -27 +52 @@ Namespace | Accepted types | How the output is used -`asset.*` | Strings, numbers, booleans | Overrides asset metadata variables (from `EXT-X-ASSET` tags) for this ad break. Available to the ADS request URL through dynamic variable substitution. For more information about HLS ad markers, see [HLS ad markers](https://docs.aws.amazon.com/mediatailor/latest/ug/hls-ad-markers.html). +`asset.*` | Strings, numbers, booleans | Overrides asset metadata variables (from `EXT-X-ASSET` tags) for this ad break. Available to the ADS request URL through dynamic variable substitution. For more information, see [HLS supported ad markers](./hls-ad-markers.html). @@ -32 +57 @@ Namespace | Accepted types | How the output is used -All output from the `PRE_ADS_REQUEST` hook are transient overrides — they apply only to the current ad break's ADS request and are not persisted to the session. +All output from the `PRE_ADS_REQUEST` hook is a transient override. It applies only to the current ad break's ADS request and is not persisted to the session. @@ -53,0 +79,2 @@ This replaces the ADS URL and adds a custom header for the current ad break. + * Query Elemental Inference for content classifications and brand safety signals to enable contextual ad targeting. + @@ -69 +96 @@ Pre-session initialization -Function types and composition +Post-ads response