# 服务器端广告插入（SSAI） Amazon IVS 服务器端广告插入（SSAI）使您能够通过视频广告来实现流媒体的盈利。IVS SSAI 与 AWS Elemental MediaTailor 集成，使您能够使用广告决策、受众定位和个性化等功能。IVS 提供了 API 操作，可将广告插播插入到您的直播流中，使您能够让创作者或运营者掌控广告的播放时间。IVS 将广告直接植入到视频流中。这提供了无缝的观看体验，并且避免了复杂的客户端逻辑。有关与 SSAI 相关的成本的信息，请参阅 [IVS 成本](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/costs.html)。 ## SSAI 入门 本教程将帮助您开始使用 Amazon IVS 服务器端广告插入（SSAI）功能。在本教程的最后，您将完成一个用于服务器端广告插入的 IVS 频道配置，并且您还将了解如何在直播流中插入广告插播。IVS SSAI 与 AWS Elemental MediaTailor 集成以处理广告决策。 ### 步骤 1：创建 IVS 频道 创建 IVS 频道。您需要该频道的播放 URL 以在下一步中配置 MediaTailor。创建频道后，请保存以下值： + **频道 ARN** – 稍后，您需要此值来更新频道。 + **播放 URL 前缀** – 从播放 URL 中提取 URL 前缀（/api/ 之前的所有内容）。例如，如果您的播放 URL 是： + https://c17b3fb37fc9.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.ABcdef12ghIJ.m3u8 前缀为： + https://c17b3fb37fc9.us-west-2.playback.live-video.net/ + **容器格式** – 必须设置为 MPEG 传输流（TS）。 ### 步骤 2：创建 MediaTailor 播放配置 创建 AWS Elemental MediaTailor 播放配置。此配置将您的广告决策服务器与 IVS 相连接，并为您的流启用广告插入功能。 播放配置使用播放 URL 前缀，该前缀在您账户及所在区域的所有 IVS 频道中都是通用的。这意味着您可以将单个 MediaTailor 播放配置用于多个 IVS 频道。 有关说明，请参阅《AWS Elemental MediaTailor 用户指南》**中的[创建 MediaTailor 播放配置](https://docs.aws.amazon.com/mediatailor/latest/ug/configurations-create.html)。创建配置时，IVS SSAI 需要进行的设置如下所示： | 设置 | 位置 | 值 | | --- | --- | --- | | 广告决策服务器 URL | 必需的设置 | 广告决策服务器的 URL | | 内容来源 | 必需的设置 | 您的 IVS 播放 URL 的 URL 前缀；例如 https://c17b3fb37fc9.us-west-2.playback.live-video.net/ | | 插入模式 | 个性化详细信息 | PLAYER\_SELECT | **重要** 仅使用频道播放 URL 的前缀（结尾为 `live-video.net/`）而不是完整 URL 来指定内容来源。如果格式不正确，则在下一步创建广告配置时就会因验证错误而失败。 ### 步骤 3：创建 IVS 广告配置 广告配置会将您的 IVS 资源与您的 MediaTailor 播放配置相关联。您可以将在任何 IVS 主区域创建的 MediaTailor 播放配置和任何其他 IVS 主区域中的广告配置结合使用。IVS 主区域包括 `us-west-2`、`us-east-1`、`eu-west-1`、`eu-central-1`、`ap-northeast-1`、`ap-northeast-2` 和 `ap-south-1`。 您可以跨多个频道重复使用单个广告配置。 要创建广告配置（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" ``` 保存响应中的 ARN 值。您在下一个步骤中需要用到它。 ### 步骤 4：使用广告配置更新频道 更新您的 IVS 频道，使其与您创建的广告配置关联。要更新频道（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" ``` ### 步骤 5：开始流式传输 使用您频道中的摄取端点和流密钥开始流式传输。 ### 步骤 6：插入广告插播 在您的流直播期间，调用 InsertAdBreak 操作来插入广告插播。指定频道 ARN 和广告插播时长（以秒为单位）。 要插入一条广告插播（AWS CLI），请执行以下操作： ``` aws ivs insert-ad-break --channel-arn "arn:aws:ivs:us-west-2:123456789012:channel/ABcdef12ghIJ" --duration-seconds 30 ``` InsertAdBreak 成功返回后，您将能够收到一个 EventBridge 事件（IVS 广告插播状态更改事件），该事件包含一个时间戳，用于指示广告插播将被插入到观众播放列表中的预计时间。这是广播公司可以合理预期广告开始替换原内容的时间点。如果无法填充广告（例如，如果您的广告决策服务器未返回广告，或者广告需要由 MediaTailor 进行转码），则显示源内容。 **重要** 在现有广告插播尚未结束之前，您不能插入新的广告插播。在当前广告插播结束之前，随后调用 InsertAdBreak 将会返回 409 `ConflictException`。 #### EventBridge 集成 通过使用 SSAI，增加了一个 IVS 广告插播状态更改事件（称为“广告插播已插入”），其包含以下字段： | 字段 | 说明 | | --- | --- | | event\_name | 正在发出的事件的名称。 | | channel\_name | 由 InsertAdBreak API 请求触发的频道的名称。 | | stream\_id | 由 InsertAdBreak API 请求触发的频道的直播流 ID。 | | ad\_break\_id | 与广告插播关联的唯一 ID，对应于初始 InsertAdBreak 请求的响应中的广告插播 ID。 | | duration\_seconds | InsertAdBreak 请求中包含并由客户指定的值（以秒为单位）。 | | target\_start\_time | 将广告插播插入到播放列表时的直播流的预计时间戳。 | ### 步骤 7：播放器 SDK 事件 在各个平台上，播放器 SDK 会在播放广告插播时触发事件，以通知广告开始时间、进展以及停止时间。下面是有关可用事件和时间的简要概述： | 事件 | 有效载荷 | 触发器 | | --- | --- | --- | | 广告插播已开始 | AdBreak | 广告插播的第一个片段 | | 广告创意已开始 | AdCreative | 每个创意的第一个片段 | | 广告时间更新 | AdTimeUpdate | 广告播放期间的每一秒 | | 广告创意已结束 | AdCreative | 每个创意的最后一个片段 | | 广告插播已结束 | AdBreak | 插播后的第一个内容片段 | 有关每个平台的特定事件和有效载荷名称，请参阅播放器 SDK 文档： + Web：请参阅 PlayerEventType 枚举，网址为 [https://aws.github.io/amazon-ivs-player-docs/latest/web/](https://aws.github.io/amazon-ivs-player-docs/latest/web/) + Android：请参阅 Player.Listener 类，网址为 [https://aws.github.io/amazon-ivs-player-docs/latest/android/](https://aws.github.io/amazon-ivs-player-docs/latest/android/) + IOS：请参阅 IVSPlayerDelegate 协议，网址为 [https://aws.github.io/amazon-ivs-player-docs/latest/ios/](https://aws.github.io/amazon-ivs-player-docs/latest/ios/) 以下是使用 Web SDK 中的广告事件在广告插播期间创建简单的广告倒计时 UI 组件的示例： ``` // 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(); }); ``` ### 录制内容中的广告标记 当通过自动录制功能将直播流录制到 Amazon S3 时，IVS 会生成并将一个 VOD 播放列表写入 S3，该列表在直播过程中触发广告的位置处包含了 SCTE-35 广告标记。有关详细信息，请参阅 [SSAI 播放列表参考](#ssai-playlist-reference)。 ### 观众体验 默认情况下，当您插入广告插播时，MediaTailor 会填充广告并向所有观众投放广告。如果您为您的流媒体使用播放授权令牌，则可以通过在播放授权 JWT 令牌中添加声明 `"aws:ads-opt-out": true` 来选择不让观众接收广告。 当观众在广告插播期间中途开始观看内容时，IVS 会将广告插播的时长向上取整到最接近的四分位数。例如，如果一位观众在 60 秒广告插播的最后 35 秒才开始观看，他将看到一个 45 秒的广告插播。 更新您的 MediaTailor 播放配置或添加新广告时，首次请求广告插播时，观众可能无法看到广告，因为 MediaTailor 首先必须对广告进行转码。几分钟后，随后再调用 InsertAdBreak 将导致观众看到广告。MediaTailor 的转码日志记录了这些转码。 ### 观众跟踪参数 在 Elemental MediaTailor 播放配置中配置广告决策服务器（ADS）时，您可以使用模板将参数传递给 ADS（请参阅 [MediaTailor 传递参数给 ADS](https://docs.aws.amazon.com/mediatailor/latest/ug/passing-paramters-to-the-ads.html)）。凭借 IVS SSAI，您可以使用该用户的播放授权令牌为每个查看器传递参数，方法是添加具有以下格式的声明： ``` "aws:ads-player-params": { "key1": "value1", "key2": "value2" } ``` 将这些参数传递给 Elemental MediaTailor，然后作为 `[player_params.key1]` 和 `[player_params.key2]` 模板变量填充。您放入此列表中的键始终以命名空间形式作为 `player_params` 模板参数处理。 所有键和值的总有效载荷大小限制为 1000 字节。 ### 报告模式 当观众观看广告时，客户端或服务器可以发送信标，以指示每个广告创意的播放进度。默认情况下，MediaTailor 在服务器端处理信标。您可以通过在播放授权令牌中添加以下声明来控制报告模式： ``` "aws:ads-reporting-mode": "CLIENT" | "SERVER" ``` 默认值为 `SERVER`。设置为 `SERVER` 时，MediaTailor 会在服务器端发送信标。设置为 `CLIENT` 时，则会禁用服务器端信标，并在 IVS 播放器 SDK adBreakStarted 事件的 `metadata.trackingData` 字段中提供跟踪数据。IVS 播放器 SDK 不调用信标 URL。 ### 已知问题 + 如果 IVS 频道 `containerFormat` 设置为 `FRAGMENTED_MP4`，则无法使用 IVS 广告。如果在广告配置中使用 FMP4 容器格式，则调用 UpdateChannel 和 CreateChannel 将会返回验证错误。 + 在广告播放过程中，在自适应比特率模式与手动选择质量模式之间切换可能会导致播放器出现卡顿和缓冲的问题。 + 对于持续时间超过 12 小时且遭遇过资源短缺情况的流媒体，其节目时间可能会出现偏差，从而导致观众无法接收到广告。解决办法是让广播公司重新开始启动播放流。 ## SSAI 播放列表参考 ### 带有 SSAI 的实时变体播放列表 当广告被植入到播放流中时，IVS 会在广告片段之前插入以下所记录的标签。 **1。植入的广告声明** ``` #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" ``` | 属性 | 说明 | | --- | --- | | ID | 格式：`stitched-ad-{timestamp}-{duration}`
`{timestamp}`：广告开始的 Unix 时间戳
`{duration}:` 广告的整数时长（以纳秒为单位）
类型：字符串数组 | | CLASS | 对于 SSAI 广告，始终为 live-video-net-stitched-ad。 | | START-DATE | ISO 8601 标准中规定的广告开始时间/日期。 | | DURATION | 广告时长（以秒为单位）。 | | X-NET-LIVE-VIDEO-AD-AD-BREAK-ID | 调用 InsertAdBreak 操作时 IVS 返回的广告插播 ID。 | **2. 流来源更改** ``` #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" ``` | 属性 | 说明 | | --- | --- | | CLASS | 始终为 live-video-net-stream-source。 | | START-DATE / END-ON-NEXT | 此来源范围的时间元数据。 | | X-NET-LIVE-VIDEO-STREAM-SOURCE | 向播放器发出的视频源正在更换的提示。主内容对应的值为“live”，广告内容对应的值为唯一ID。 | **3. 不连续性标记** ``` #EXT-X-DISCONTINUITY ``` 标准的 HLS 标签，表明在直播流和广告内容之间，编码参数可能会发生变化。 #### 广告片段 ``` #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 ``` | 属性 | 说明 | | --- | --- | | EXT-X-PROGRAM-DATE-TIME | 此片段的时间戳。 | | EXTINF | 格式：`{duration},{tag}`
`{duration}`：片段时长（以秒为单位）。
`{tag}`：源标识符。对于直播内容，该值始终为 `live`。对于广告内容，该值为 MediaTailor 提供的 UUID，用于唯一标识广告素材的转码产物 | | 片段 URL | IVS 托管的端点，包含有关片段及其在 IVS 缓存中位置的加密信息。 | ### 带有 SSAI 的 VOD 变体播放列表 录制直播流时，IVS 会生成并将一个 VOD 播放列表写入 S3，该列表在直播过程中触发广告的位置处包含了 SCTE-35 广告标记。要在 VOD 播放期间投放广告，您需通过 MediaTailor 提供该 IVS 播放列表，MediaTailor 负责将广告片段植入到播放列表中。MediaTailor 将广告插播期间的原始 VOD 片段替换为广告片段。 **1。广告插播开始标记（SCTE35-OUT）** ``` #EXT-X-DATERANGE:ID="12345678",START-DATE="2025-12-06T00:45:45.723Z",PLANNED-DURATION=20.0,SCTE35-OUT=0xFC302000000000000000FFF00F05F8E7AEFC7FFFFE001B7740000000000000340CFD88 ``` | 属性 | 说明 | | --- | --- | | ID | 此广告插播的唯一标识符。用于关联开始标记和结束标记。 | | START-DATE | ISO 8601 标准中规定的广告插播开始时间/日期。 | | PLANNED-DURATION | 广告插播的预期时长（以秒为单位）。 | | SCTE35-OUT | SCTE-35 标记，标志着广告插播的开始。 | **2. 广告片段（MediaTailor 植入）** ``` #EXTINF:2.0, ../../../../segment/b2857627df9428679e888ee8daa979d0b7559801/gk-test-ivs-vod/bd0c7d90-a47c-4a91-b5ec-7d0f9897049b/0/3 ``` | 属性 | 说明 | | --- | --- | | EXTINF | 广告片段的时长（以秒为单位）。 | | Segment URL | MediaTailor 托管的广告片段的相对路径。 | **3. 广告插播结束标记（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 ``` | 属性 | 说明 | | --- | --- | | ID | 与起始标记的 ID 相同。将两者关联在一起。 | | START-DATE | 广告插播的原始开始时间（与开始标记相同）。 | | END-DATE | 广告插播结束时对应的 ISO 8601 时间戳。 | | DURATION | 广告插播的实际时长（以秒为单位）。 | | SCTE35-IN | SCTE-35 标记，标志着广告插播的结束。 |