# サーバー側の広告挿入 (SSAI)
<a name="server-side-ad-insertion"></a>

Amazon IVS サーバー側の広告挿入 (SSAI) を使用すると、動画広告でストリームを収益化できます。IVS SSAI は AWS Elemental MediaTailor と統合されており、広告の決定、オーディエンスターゲティング、パーソナライゼーションなどの機能にアクセスできます。IVS には、ライブストリームに広告時間枠を挿入する API オペレーションが用意されているため、クリエーターやオペレーターが広告の実行タイミングを制御できるようになります。IVS は広告をビデオストリームに直接ステッチします。これにより、シームレスな表示エクスペリエンスが提供され、複雑なクライアント側のロジックを回避できます。SSAI に関連するコストについては、「[IVS コスト](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/costs.html)」を参照してください。

## SSAI の開始方法
<a name="ssai-getting-started-with-ssai"></a>

このチュートリアルは、Amazon IVS サーバー側の広告挿入 (SSAI) の使用を開始するのに役立ちます。このチュートリアルの最後に、サーバー側の広告挿入用に IVS チャネルが設定され、ライブストリームに広告時間枠を挿入する方法がわかります。IVS SSAI は AWS Elemental MediaTailor と統合されており、広告の決定を処理します。

### ステップ 1: IVS チャネルを作成する
<a name="ssai-getting-started-with-ssai-step-1"></a>

IVS チャネルを作成します。次のステップで MediaTailor を設定するには、チャネルの再生 URL が必要です。チャネルを作成したら、次の値を保存します。
+ **チャネル 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 再生設定を作成する
<a name="ssai-getting-started-with-ssai-step-2"></a>

AWS Elemental MediaTailor 再生設定を作成します。この設定では、広告決定サーバーを IVS に接続し、ストリームの広告挿入を有効にします。

再生設定では、アカウントやリージョンにまたがってすべての IVS チャネルに共通する再生 URL プレフィックスを使用します。つまり、複数の IVS チャネルで単一の MediaTailor 再生設定を使用できます。

手順については、「[AWS Elemental MediaTailor ユーザーガイド](https://docs.aws.amazon.com/mediatailor/latest/ug/configurations-create.html)」の「*MediaTailor 再生設定の作成*」を参照してください。設定を作成するときは、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 広告設定を作成する
<a name="ssai-getting-started-with-ssai-step-3"></a>

広告設定は、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: 広告設定でチャネルを更新する
<a name="ssai-getting-started-with-ssai-step-4"></a>

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: ストリーミングを開始する
<a name="ssai-getting-started-with-ssai-step-5"></a>

チャネルから取り込んだエンドポイントとストリームキーを使用してストリーミングを開始します。

### ステップ 6: 広告時間枠を挿入する
<a name="ssai-getting-started-with-ssai-step-6"></a>

ストリームのライブ中に 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 統合
<a name="ssai-getting-started-with-ssai-step-6-eventbridge-integration"></a>

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: Player SDK イベント
<a name="ssai-getting-started-with-ssai-step-7"></a>

プラットフォーム全体で、Player SDK は広告時間枠が再生されたときのイベントを表示し、広告が開始、進行、および停止したタイミングを通知します。利用可能なイベントとタイミングの概要を次に示します。


| イベント | ペイロード | Trigger トリガー) | 
| --- | --- | --- | 
| 広告時間枠が開始されました | AdBreak | 広告時間枠の最初のセグメント | 
| 広告クリエイティブが開始されました | AdCreative | 各クリエイティブの最初のセグメント | 
| 広告時刻更新 | AdTimeUpdate | 広告の再生中 1 秒ごと | 
| 広告クリエイティブが終了しました | AdCreative | 各クリエイティブの最後のセグメント | 
| 広告時間枠が終了しました | AdBreak | 時間枠終了後の最初のコンテンツセグメント | 

各プラットフォームの特定のイベント名とペイロード名については、次の Player SDK ドキュメントを参照してください。
+ ウェブ: PlayerEventType 列挙については、[https://aws.github.io/amazon-ivs-player-docs/latest/web/](https://aws.github.io/amazon-ivs-player-docs/latest/web/) を参照してください。
+ Android: [https://aws.github.io/amazon-ivs-player-docs/latest/android/](https://aws.github.io/amazon-ivs-player-docs/latest/android/) で Player.Listener クラスを参照してください。
+ IOS: [https://aws.github.io/amazon-ivs-player-docs/latest/ios/](https://aws.github.io/amazon-ivs-player-docs/latest/ios/) で IVSPlayerDelegate プロトコルを参照してください。

以下は、ウェブ 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(); 
});
```

### 記録されたコンテンツの広告マーカー
<a name="ssai-getting-started-with-ssai-ad-markers"></a>

Amazon S3 への自動録画を使用してライブストリームが記録されると、IVS はライブストリーム中に広告がトリガーされた位置に SCTE-35 広告マーカーを含む VOD プレイリストを生成して S3 に書き込みます。詳細については、「[SSAI プレイリストリファレンス](#ssai-playlist-reference)」を参照してください。

### 視聴者エクスペリエンス
<a name="ssai-getting-started-with-ssai-viewer-experience"></a>

デフォルトでは、広告時間枠を挿入すると、MediaTailor はすべての視聴者に広告を埋めて配信します。ストリームに再生認可トークンを使用している場合は、再生認可 JWT トークンにクレーム `"aws:ads-opt-out": true` を追加することで、視聴者による広告の受信をオプトアウトできます。

視聴者が広告時間枠の途中でストリーミングを開始すると、IVS は広告時間枠の期間を 15 秒単位に切り上げます。例えば、60 秒の広告時間枠に残り 35 秒で参加する視聴者には、45 秒の広告時間枠が発生します。

MediaTailor の再生設定を更新したり、新しい広告を追加したりすると、MediaTailor はまず広告をトランスコーディングする必要があるため、広告時間枠を初めてリクエストしたときに視聴者に広告が表示されないことがあります。数分後に改めて InsertAdBreak を呼び出すと、視聴者に広告が表示されます。MediaTailor のトランスコーディングログは、これらのトランスコーディングを記録します。

### 視聴者追跡パラメータ
<a name="ssai-getting-started-with-ssai-viewer-tracking-parameters"></a>

Elemental MediaTailor PlaybackConfiguration で広告決定サーバー (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 バイトに制限されています。

### レポートモード
<a name="ssai-getting-started-with-ssai-reporting-mode"></a>

視聴者が広告を視聴すると、クライアントまたはサーバーは各広告クリエイティブの再生の進行状況を示すビーコンを送信できます。デフォルトでは、MediaTailor はサーバー側でビーコン送信を処理します。再生認可トークンに次のクレームを追加することで、レポートモードを制御できます。

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

デフォルト値は `SERVER` です。`SERVER` に設定すると、MediaTailor はサーバー側でビーコンを送信します。`CLIENT` に設定すると、サーバー側のビーコン送信が無効になり、IVS Player SDK adBreakStarted イベントの `metadata.trackingData` フィールドに追跡データが提供されます。IVS プレイヤー SDK はビーコン URL 呼び出しません。

### 既知の問題
<a name="ssai-getting-started-with-ssai-known-issues"></a>
+ IVS チャネル `containerFormat` が `FRAGMENTED_MP4` に設定されている場合、IVS 広告は機能しません。UpdateChannel と CreateChannel を呼び出すと、広告設定で FMP4 コンテナ形式が使用されている場合、検証エラーが返されます。
+ 広告の再生中に、アダプティブビットレートモードと手動品質選択を切り替えると、プレイヤーでフリーズやバッファリングの問題が発生する可能性があります。
+ リソースの枯渇が発生した 12 時間を超えるストリームの場合、プログラムの日付時刻がドリフトし、視聴者に広告が配信されない可能性があります。回避策は、ブロードキャスターがストリームを再起動することです。

## SSAI プレイリストリファレンス
<a name="ssai-playlist-reference"></a>

### SSAI を使用したライブバリアントプレイリスト
<a name="ssai-playlist-reference-live"></a>

広告がストリームにステッチされると、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}`<br />`{timestamp}`: 広告開始の Unix タイムスタンプ<br />`{duration}:` ナノ秒単位の整数としての広告期間<br />型: 文字列の配列 | 
| 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 | ビデオソースが変更されているプレイヤーのヒント。値は、プライマリコンテンツの場合はライブ、広告コンテンツの場合は一意の ID です。 | 

**3. 不連続マーカー**

```
#EXT-X-DISCONTINUITY
```

そのエンコード用パラメータを示す標準 HLS タグは、ライブストリームと広告コンテンツでは異なる可能性があります。

#### 広告セグメント
<a name="ssai-playlist-reference-live-ad-segments"></a>

```
#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}`<br />`{duration}`: セグメントの長さ (秒単位)。<br />`{tag}`: ソース識別子。ライブコンテンツの場合、これは常に `live` です。広告コンテンツの場合、これは MediaTailor が提供する UUID で、広告アセットトランスコーディングを一意に識別します。 | 
| セグメント URL | IVS キャッシュ内のセグメントとその場所に関する暗号化された情報を含む IVS ホストエンドポイント。 | 

### SSAI を使用した VOD バリアントプレイリスト
<a name="ssai-playlist-reference-vod"></a>

ライブストリームが記録されると、IVS はライブストリーム中に広告がトリガーされた位置に SCTE-35 広告マーカーを含む VOD プレイリストを生成して S3 に書き込みます。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 マーカー。 |