Server-Side Ad Insertion (SSAI)

Amazon IVS server-side ad insertion (SSAI) enables you to monetize your streams with video ads. IVS SSAI integrates with AWS Elemental MediaTailor, giving you access to capabilities such as ad decisioning, audience targeting, and personalization. IVS provides an API operation to insert ad breaks into your live stream, allowing you to give creators or operators control over when ads run. IVS stitches ads directly into the video stream. This provides a seamless viewing experience and avoids complex client-side logic. For information about costs associated with SSAI, see IVS Costs.

Getting Started with SSAI

This tutorial helps you get started with Amazon IVS server-side ad insertion (SSAI). At the end of this tutorial, you will have an IVS channel configured for server-side ad insertion, and you will know how to insert ad breaks into your live stream. IVS SSAI integrates with AWS Elemental MediaTailor to handle ad decisioning.

Step 1: Create an IVS Channel

Create an IVS channel. You need the channel's playback URL to configure MediaTailor in the next step. After creating your channel, save the following values:

Step 2: Create a MediaTailor Playback Configuration

Create an AWS Elemental MediaTailor playback configuration. This configuration connects your ad decision server to IVS and enables ad insertion for your streams.

The playback configuration uses the playback URL prefix, which is common across all IVS channels in your account and region. This means you can use a single MediaTailor playback configuration with multiple IVS channels.

See Creating a MediaTailor Playback Configuration in the AWS Elemental MediaTailor User Guide for instructions. When creating the configuration, the following settings are required for IVS SSAI:

Step 3: Create an IVS Ad Configuration

An ad configuration links your IVS resources to your MediaTailor playback configuration. You can use a MediaTailor playback configuration created in any IVS home region with an ad configuration in any other IVS home region. IVS home regions include us-west-2, us-east-1, eu-west-1, eu-central-1, ap-northeast-1, ap-northeast-2, and ap-south-1.

You can reuse a single ad configuration across multiple channels.

To create an ad configuration (AWS CLI):

aws ivs create-ad-configuration --name "my-ad-config" --media-tailor-playback-configurations playbackConfigurationArn="arn:aws:mediatailor:us-west-2:123456789012:playbackConfiguration/my-mediatailor-config"

Save the arn value from the response. You need it in the next step.

Step 4: Update the Channel with the Ad Configuration

Update your IVS channel to associate it with the ad configuration you created. To update the channel (AWS CLI):

aws ivs update-channel --arn "arn:aws:ivs:us-west-2:123456789012:channel/ABcdef12ghIJ" --ad-configuration-arn "arn:aws:ivs:us-west-2:123456789012:ad-configuration/ABcdef12ghIJ"

Step 5: Start Streaming

Use the ingest endpoint and stream key from your channel to start streaming.

Step 6: Insert Ad Break

While your stream is live, call the InsertAdBreak operation to insert an ad break. Specify the channel ARN and the duration (in seconds) for the ad break.

To insert an ad break (AWS CLI):

aws ivs insert-ad-break --channel-arn "arn:aws:ivs:us-west-2:123456789012:channel/ABcdef12ghIJ" --duration-seconds 30

Upon successful return of InsertAdBreak, you can receive an EventBridge event (IVS Ad Break State Change) that contains a timestamp indicating the expected time the ad break will be inserted into viewer playlists. This is the time when the broadcaster can reasonably expect ads to begin replacing content. If an ad cannot be filled (for example, if your ad decision server does not return an ad or ads need to be transcoded by MediaTailor), source content is shown instead.

EventBridge Integration

With SSAI, an IVS Ad Break State Change event (called Ad Break Inserted) is added, with the following fields:

Step 7: Player SDK Events

Across platforms, the Player SDK surfaces events when an ad break is played, notifying when an ad starts, progresses, and stops. Here is a high-level summary of the available events and timing:

For the specific event and payload names for each platform, see the Player SDK documentation:

Below is an example of using ad events in the Web SDK to create a simple ad countdown UI component during an ad break:

// State 
let podLength = 0;  
let podIndex = 0; 
let remainingSeconds = 0; 
 
// Fired every second during the ad break 
player.addEventListener(PlayerEventType.AD_TIME_UPDATE, (payload) => { 
    podLength = payload.podLength; 
    podIndex = payload.podIndex; 
    remainingSeconds = Math.round(payload.creativeDuration - payload.creativeElapsed); 
    const text = `Ad ${podIndex} of ${podLength} · ${remainingSeconds}s remaining` 
    // Ad 1 of 2 · 20s remaining 
    console.log('Ad countdown text', text); 
    UpdateAdOverlay(text); 
}); 

// Fired when the ad break ends  
player.addEventListener(PlayerEventType.AD_BREAK_ENDED, (payload) => { 
    hideAdOverlay(); 
});

Ad Markers in Recorded Content

When a live stream is recorded using auto-record to Amazon S3, IVS generates and writes a VOD playlist to S3 that includes SCTE-35 ad markers at the positions where ads were triggered during the live stream. See SSAI Playlist Reference for details.

Viewer Experience

By default, MediaTailor fills and serves ads to all viewers when you insert an ad break. If you are using playback authorization tokens for your streams, you can opt viewers out of receiving ads by adding the claim "aws:ads-opt-out": true to your playback authorization JWT token.

When viewers begin streaming partway through an ad break, IVS rounds up the ad break duration to the nearest quartile. For example, a viewer who joins with 35 seconds remaining in a 60-second ad break will experience a 45-second ad break.

When updating your MediaTailor playback configuration or adding new ads, viewers might not see ads the first time you request an ad break because MediaTailor must first transcode the ads. After a few minutes, subsequent calls to InsertAdBreak will result in viewers seeing ads. MediaTailor’s transcode logs record these transcodes.

Viewer Tracking Parameters

When configuring an Ad Decisioning Server (ADS) in your Elemental MediaTailor PlaybackConfiguration, you can pass parameters to the ADS using templates (see MediaTailor passing parameters to ADS). With IVS SSAI, you can pass parameters for each viewer using the playback authorization token for that user, by adding a claim with the following format:

"aws:ads-player-params": { 
   "key1": "value1", 
   "key2": "value2" 
}

These parameters are passed to Elemental MediaTailor to be filled as the [player_params.key1] and [player_params.key2] template variables. Keys that you put in this list are always namespaced as player_params template parameters.

The total payload size for all keys and values combined is limited to 1000 bytes.

Reporting Mode

As a viewer watches an ad, the client or server can send beacons indicating playback progress for each ad creative. By default, MediaTailor handles beaconing on the server side. You can control the reporting mode by adding the following claim to the playback authorization token:

"aws:ads-reporting-mode": "CLIENT" | "SERVER"

The default value is SERVER. When set to SERVER, MediaTailor sends beacons on the server side. When set to CLIENT, server-side beaconing is disabled and tracking data is provided in the metadata.trackingData field of the IVS Player SDK adBreakStarted event. The IVS player SDK does not call beacon URLs.

Known Issues

SSAI Playlist Reference

Live Variant Playlist with SSAI

When an ad is stitched into the stream, IVS inserts the tags documented below, before the ad segments.

1. Stitched Ad Declaration

#EXT-X-DATERANGE:ID="stitched-ad-1765566299-20000000000",CLASS="live-video-net-stitched-ad",START-DATE="2025-12-12T19:04:59.079Z",DURATION=20.000,X-NET-LIVE-VIDEO-AD-AD-BREAK-ID="test"

2. Stream Source Change

#EXT-X-DATERANGE:ID="source-1765566299",CLASS="live-video-net-stream-source",START-DATE="2025-12-12T19:04:59.079Z",END-ON-NEXT=YES,X-NET-LIVE-VIDEO-STREAM-SOURCE="0f262e65-a709-4ef1-8741-e82d936c"

3. Discontinuity Marker

#EXT-X-DISCONTINUITY

Standard HLS tag signaling that encoding parameters may change between the live stream and the ad content.

Ad Segments

#EXT-X-PROGRAM-DATE-TIME:2025-12-12T19:04:59.079Z 
#EXTINF:2.000,0f262e65-a709-4ef1-8741-e82d936c 
https://4ce388b1cf28.j.cloudfront.hls.live-video.net/v1/segment/CvsCse8Qbs5DU_aRmrVLd72_nK9lo9xS1KjD115LsIXcsD27JfLfkSuamLUivqOTrfHUeGf6Zmx_c9rhq0btTOu7E4F1DaU8knNoebLq6FlKp6q8ysaQdEA10gKCNP92oAQ_0DGLInY462O9HUxgtk5KHj23ZjPhVCxIh3DjWqwaevDci1_q7dYL55rgSKd11SfpsGSS9Yup4g5dfzyGhfz6Y2Skaj34JtoVyd8Nxlppc4jDlZl-6j7YM1i2qdUcM3VNWrZrxCisBXgOPtI3vFdeNcNjPzVdOGjMz5cXcQIp8YOCwnkdkomhn_3xxmB1Zngl3QPao6-oPsjH3qVcMOCuKfKZSmRJGFLvkrO1PefV5ya3eUvihXCMvDE-81EmGp5q9ErEgFpz06rMDbYFWb3z9H8X0t8KzvGDOaqKTYHZ0lgEV-fULeDQ76pDy_OVPwhO2vJMxBpfdQ_IeB1QUK2wJmXJ96Mvv0C2dcb0F7zE3lr_iBGemUjwmb7JmBoM3HdJbpV0TGp8C6vhIAEqCXVzLXdlc3QtMjD3DQ.ts?dna=CmanuVzG9F6kGS2X7ThbGZyZPHWgX2TiBlBMYsvGWLcWaLWyntTaWRp5D9qjZsrGKkzdwoLNY4pri6ZgpxnzqLqWvhcP6zoGu8vifP5NxPgiNKMmYdUmQrqTAf7jbauvE3c6B9ebptAaDEkrbrnG1qF8Cv3kbiABKgl1cy13ZXN0LTIw9w0

VOD Variant Playlist with SSAI

When a live stream is recorded, IVS generates and writes a VOD playlist to S3 that includes SCTE-35 ad markers at the positions where ads were triggered during the live stream. To serve ads during VOD playback, you serve this IVS playlist through MediaTailor, which is responsible for stitching ad segments into the playlist. MediaTailor replaces the original VOD segments during the ad break with ad segments.

1. Ad Break Start Marker (SCTE35-OUT)

#EXT-X-DATERANGE:ID="12345678",START-DATE="2025-12-06T00:45:45.723Z",PLANNED-DURATION=20.0,SCTE35-OUT=0xFC302000000000000000FFF00F05F8E7AEFC7FFFFE001B7740000000000000340CFD88

2. Ad Segments (MediaTailor Stitched)

#EXTINF:2.0, ../../../../segment/b2857627df9428679e888ee8daa979d0b7559801/gk-test-ivs-vod/bd0c7d90-a47c-4a91-b5ec-7d0f9897049b/0/3

3. Ad Break End Marker (SCTE35-IN)

#EXT-X-DATERANGE:ID="12345678",START-DATE="2025-12-06T00:45:45.723Z",END-DATE="2025-12-06T00:46:07.889Z",DURATION=20.0,SCTE35-IN=0xFC302000000000000000FFF00F05F8E7AEFC7F7FFE001B7740000000000000C23E5851