View a markdown version of this page

Post-ads response - AWS Elemental MediaTailor
When it firesInputOutput namespace allowedWhat this hook doesn't seeTypical use casesFailure behavior

Post-ads response

When it fires

MediaTailor runs the function mapped to POST_ADS_RESPONSE after it receives and parses a response from the ADS, including resolution of VAST wrapper redirects. The function sees the parsed ads before MediaTailor selects ads to insert, so changes made here influence which ads fill the ad break.

The hook fires for all streaming protocols (HLS and DASH) and all playback modes (live, VOD, and pre-roll). It typically fires once per ad break. For ADS responses that cover multiple ad breaks at once (such as VMAP responses) and for prefetched ad responses, the hook fires when MediaTailor processes the response, and the avail input namespace is not present. Use $exists(avail) to check before accessing avail fields.

Input

event.*, session.*, adsRequest.*, and adsResponse.*, plus avail.* when the response applies to a single ad break. For all available fields, see Input field reference.

Output namespace allowed

Namespace Accepted types How the output is used
adsResponse.ads Array of ad objects Replaces the parsed ad list for this response. MediaTailor matches each returned ad to the original ads by adId and proceeds to ad selection with the returned list.
temp.* Any Temporary data for passing values between steps in an executor. Not persisted.

Write the modified ad list back to adsResponse.ads. You can:

  • Filter — return a subset of the original ads. Ads you omit are not considered for insertion, and the duration they occupied becomes available for other ads to fill.

  • Reorder — return the ads in a different order. Order affects which ads fill the ad break first.

  • Modify — change durationSeconds, adSystem, adTitle, mediaFiles, or trackingEvents on an ad. Ads returned unchanged keep all of their original VAST metadata.

  • Inject — add ads that were not in the original response. A new entry must include adId, durationSeconds, and mediaFiles. Ads fetched with a VAST_REQUEST function in the same hook invocation are an exception: appending such an ad by its adId is enough, because MediaTailor restores the ad's complete parsed VAST data. For more information, see VAST request.

Important

Always use a JSONata array constructor or array coercion when filtering. A filter expression such as adsResponse.ads[adSystem != 'BLOCKED'] produces a single object when exactly one ad matches. It produces no value at all when zero ads match. In that case the output key is omitted and the filter has no effect. Wrap the expression in brackets or append []:

{
    "Output": {
        "adsResponse.ads": "{%adsResponse.ads[adSystem != 'BLOCKED'][]%}"
    }
}

The following rules apply to the returned ad list:

  • If two entries share an adId, the first occurrence wins.

  • Invalid entries are rejected individually. Valid entries in the same output still apply.

  • If an injected entry's adId collides with an ad from the ADS response, the original ad is used as the base and your field changes are applied on top of it.

What this hook doesn't see

This hook runs before ad selection, so it doesn't see ads that other MediaTailor features contribute later, and it can't determine which ads will ultimately be inserted, because transcode status and fill decisions happen afterward. For prefetched ads, the hook fires when MediaTailor processes the prefetch response itself. At a later ad break, those previously prefetched ads are merged after this hook runs, so the hook doesn't see them there. To act on the final ad set, use PRE_MANIFEST_INSERTION.

Typical use cases

  • Filter ads by metadata, such as removing ads from competing ad systems so they don't appear in the same ad break (competitive separation).

  • Fetch additional ads from a secondary ad server with a VAST_REQUEST function when the primary response is short, and append them to the ad list.

  • Reorder ads so that preferred ads fill the ad break first.

  • Modify tracking events or ad metadata before insertion.

Failure behavior

If a function attached to POST_ADS_RESPONSE fails for any reason, such as a timeout, an expression error, or invalid output, MediaTailor discards the function's output. The request proceeds with the original ADS response, as if no function were attached. If the serialized input exceeds the input size limit, MediaTailor skips the hook invocation entirely. For the limits that apply, see Limits.