IF standard live event with personalized ads (<500K concurrent):
  → Standard SSAI (1:1 personalized sessions)
IF >500K concurrent:
  → Standard SSAI, PLUS contact AWS Support at least 2 weeks ahead for capacity
  → See "Scaling for Large Events" below before proposing any architecture change
IF extreme scale:
  → Multi-region MediaTailor + CDN mid-tier caching
  → LOAD references/workflow-resilience-patterns.md for multi-region scaling
IF schedule-driven VOD channel with ad breaks:
  → Channel Assembly with SSAI

Source → MediaLive (SCTE-35 passthrough) → MediaPackage v2
  → MediaTailor (fetches the origin manifest, personalizes per session)
    → CloudFront: /v1/master, /v1/manifest, /v1/dash, /v1/session, /v1/tracking, /segment
  → CloudFront: /out/v1/* content segments direct from MediaPackage, bypassing MediaTailor

AWS does NOT recommend positioning a CDN between a content origin and MediaTailor. MediaTailor already holds a fetched origin manifest and serves it to more than one session, so origin fetches sit well below player requests. The exception is a channel assembly content source, where AWS recommends a CDN in between. See service-rules-cloudfront.md.

Actions:

Create the MediaTailor playback configuration (content source URL + ADS URL). Any public HLS or DASH origin qualifies, not only MediaPackage
Configure CdnConfiguration prefixes (content and ad segment) so segment URLs route through CloudFront
Configure SlateAdUrl if the break should show slate rather than the underlying content. Slate is live and live-to-VOD only, optional for non-VPAID and mandatory for VPAID
Set AdMarkerPassthrough only if downstream players or analytics need the original break boundaries. It is HLS only, defaults to false, and gates EXT-X-CUE-OUT, EXT-X-CUE-IN and EXT-X-SPLICEPOINT-SCTE35. EXT-X-DATERANGE passes through regardless

SCTE-35 chain validation (all MUST be true):

MediaLive: Scte35Type: SCTE_35_WITHOUT_SEGMENTATION in CmafIngestGroupSettings
MediaLive: EXT-X-PROGRAM-DATE-TIME included in HLS/CMAF output
MediaPackage v2: exposes SCTE-35 in the manifest
MediaTailor: receives markers in manifest

CDN cache rules:

Manifest, session and tracking behaviours: TTL=0, forward all query strings and User-Agent
Ad segment behaviour: cache hard, and forward nothing. Ad segments are identical for every viewer, so forwarding query strings or headers gives each viewer a private cache entry
Content segments: TTL=24h+, served from MediaPackage, never through MediaTailor

Validation: a GET of the playback URL returns a personalized multivariant playlist. The ad segments are in the per-session media playlist under /v1/manifest/..., not in the multivariant playlist, so agents MUST follow a variant URI to confirm stitching.

Extreme Scale


Preconditions	Standard SSAI working; CDN mid-tier cache configured; AWS Support engaged
Use when	Concurrency far above the 500K Support-engagement threshold

SSAI manifests are personalized per session by design, so there is no mode that coalesces viewers onto a shared manifest. Scale the session count, do not try to reduce it.

IF viewership is at extreme scale:
  → Confirm AWS Support has capacity in place for the event before anything else
  → Deploy CDN mid-tier caching between viewers and MediaTailor
  → Enable CloudFront Origin Shield on the MediaTailor origin to cut requests reaching MediaTailor
  → Deploy MediaTailor in multiple regions and route session init to the nearest
IF audience-specific content (not ad personalization) is the requirement:
  → That is Channel Assembly Program Rules, not an SSAI scaling mode. Audience cohorts there select
    alternate media on a STANDARD tier LINEAR channel
  → LOAD references/workflow-linear-channel.md

Scaling for Large Events


Preconditions	Standard SSAI deployed and tested
Decision triggers	Expected concurrency >500K, multi-region requirement, ADS latency concerns

Decision: Scaling pattern

IF expected concurrency >500K:
  → Contact AWS Support at least 2 WEEKS before the event so capacity is in place for ad
    personalization. This is the documented first step and no CDN design substitutes for it
  → Request quota increases through the Service Quotas console in the same window
  → Enable CloudFront Origin Shield on the MediaTailor origin. It reduces the requests reaching
    MediaTailor, NOT MediaTailor's own fetches from the content origin
  → Enable prefetch for mid-roll ad breaks, and price it first: every prefetched creative
    MediaTailor transcodes is billed at the standard transcoding rate whether or not it is consumed
IF a multi-region deployment is required:
  → Deploy MediaTailor in multiple regions, with a playback configuration per region
  → Route session init to the nearest region
  → For CloudFront media quality aware routing, an origin group with the media quality score
    option and a matching MediaTailor configuration in each region are both required
  → LOAD references/workflow-resilience-patterns.md for multi-region patterns
IF ADS latency >1500ms P90:
  → Tune AdsRequestTimeoutMilliseconds, and use prefetch to take the ADS call off the manifest path
  → TPS-based traffic shaping is a PREFETCH schedule feature, not a general ADS latency control
IF VAST beacons point to non-functional endpoints:
  → Fix the beacon endpoints. ?aws.reportingMode=CLIENT stops MediaTailor firing them, which
    moves ALL beaconing to the player: an unmodified player then reports nothing and impressions
    go to zero. Agents MUST confirm the player fires beacons from the tracking endpoint first

Pipeline locking (recommended for failover-sensitive workflows): Pipeline locking on MediaLive matches segment numbers across both pipelines so a pipeline failover does not break in-flight MediaTailor sessions. It is RECOMMENDED for large-scale or failover-sensitive SSAI deployments. Without it, SSAI still works under steady-state but a pipeline failover may cause player session reinitialization or brief glitches.

Monitoring Thresholds

Metric	Typical target	If exceeded
`AdDecisionServer.Errors`	<1%	Investigate ADS health
`AdDecisionServer.Timeouts`	<1%	Check ADS latency, increase timeout
`Avail.FillRate`	operator target only	Planned simple average of per-avail fill percentages, not percent of breaks filled. Use metric math on `Avail.FilledDuration` / `Avail.Duration` for a duration-weighted rate
`GetManifest.Errors`	<1%	Check origin health
`GetManifest.Latency` P90	<1500ms	Investigate origin health, or CloudFront Origin Shield on the MediaTailor origin

Common Mistakes

Mistake	Consequence	Fix
Caching personalized manifests	All viewers see same ads	TTL=0 on every MediaTailor manifest and session behaviour
Forwarding query strings on the ad segment behaviour	Per-viewer ad segment cache entries; CDN and MediaTailor ad delivery out both rise	Forward nothing on `/tm/`. Keep full forwarding on `/segment/`, which is the beacon redirect
Reusing a `<Creative id>`	The older stored ad plays, with no error, no skip reason and no metric	A unique id per creative
Migrating from implicit `GET` to `POST /v1/session`	Reporting mode flips to client-side, MediaTailor stops firing beacons, impressions go to zero silently	Confirm who fires beacons before changing the entry point
Not forwarding User-Agent	ADS receives CDN user agent	Forward User-Agent header through CDN
Not forwarding query strings	Ad targeting variables lost	Forward all query strings
Missing SCTE-35 at any chain point	No ad breaks detected	Verify at each service (see rules file)

references/workflow-ad-insertion.md

Raw file

aws/agent-toolkit-for-aws