Serverseitige Werbeeinblendung (SSAI)

Mit der serverseitigen Werbeeinblendung (Server-Side Ad Insertion, SSAI) von Amazon IVS können Sie Ihre Streams durch Videowerbung monetarisieren. IVS-SSAI ist in AWS Elemental MediaTailor integriert und bietet Zugriff auf Funktionen wie Ad Decisioning, Zielgruppenansprache und Personalisierung. IVS bietet einen API-Vorgang zum Einfügen von Werbepausen in den Live-Stream, sodass Sie den Creatorn oder Betreibern die Kontrolle darüber geben können, wann Werbung geschaltet wird. IVS fügt Werbung direkt in den Videostream ein. Das sorgt für ein nahtloses Seherlebnis und macht eine komplexe clientseitige Logik überflüssig. Weitere Informationen zu den mit SSAI verbundenen Kosten finden Sie unter IVS-Kosten.

Erste Schritte mit SSAI

Dieses Tutorial hilft Ihnen beim Einstieg in die serverseitige Werbeeinblendung (SSAI) von Amazon IVS. Am Ende dieses Tutorials verfügen Sie über einen IVS-Kanal, der für die serverseitige Werbeeinblendung konfiguriert ist. Außerdem wissen Sie dann, wie Werbepausen in den Live-Stream eingefügt werden. IVS-SSAI ist für die Durchführung von Ad Decisioning in AWS Elemental MediaTailor integriert.

1. Schritt: IVS-Kanal erstellen

Erstellen Sie einen IVS-Kanal. Sie benötigen die Wiedergabe-URL des Kanals, um MediaTailor im nächsten Schritt zu konfigurieren. Speichern Sie nach Erstellung des Kanals die folgenden Werte:

2. Schritt: Wiedergabekonfiguration für MediaTailor erstellen

Erstellen Sie eine Wiedergabekonfiguration für AWS Elemental MediaTailor. Diese Konfiguration verbindet den Ad Decision Server mit IVS und ermöglicht die Werbeeinblendung für Ihre Streams.

Die Wiedergabekonfiguration nutzt das Präfix der Wiedergabe-URL, das für alle IVS-Kanäle in Ihrem Konto und Ihrer Region gilt. Das bedeutet, dass Sie eine einzige Wiedergabekonfiguration für MediaTailor bei mehreren IVS-Kanälen verwenden können.

Entsprechende Anweisungen finden Sie unter Erstellen einer Wiedergabekonfiguration für MediaTailor im Benutzerhandbuch von AWS Elemental MediaTailor. Beim Erstellen der Konfiguration sind die folgenden Einstellungen für IVS-SSAI erforderlich:

3. Schritt: IVS-Werbekonfiguration erstellen

Eine Werbekonfiguration verknüpft Ihre IVS-Ressourcen mit der Wiedergabekonfiguration für MediaTailor. Sie können eine in einer beliebigen IVS-Heimatregion erstellte Wiedergabekonfiguration für MediaTailor zusammen mit einer Werbekonfiguration in einer beliebigen anderen IVS-Heimatregion verwenden. Zu den IVS-Heimatregionen gehören us-west-2, us-east-1, eu-west-1, eu-central-1, ap-northeast-1, ap-northeast-2 und ap-south-1.

Sie können eine einzelne Werbekonfiguration für mehrere Kanäle verwenden.

So erstellen Sie eine Werbekonfiguration (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"

Speichern Sie den ARN-Wert aus der Antwort. Sie benötigen ihn im nächsten Schritt.

4. Schritt: Kanal mit der Werbekonfiguration aktualisieren

Aktualisieren Sie Ihren IVS-Kanal, um ihn mit der erstellten Werbekonfiguration zu verknüpfen. So aktualisieren Sie den Kanal (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. Schritt: Streaming starten

Verwenden Sie den Aufnahme-Endpunkt und den Streamschlüssel aus Ihrem Kanal, um mit dem Streaming zu beginnen.

6. Schritt: Werbepause einfügen

Rufen Sie während des laufenden Streams den Vorgang InsertAdBreak auf, um eine Werbepause einzufügen. Geben Sie die Kanal-ARN und die Dauer (in Sekunden) für die Werbepause an.

So fügen Sie eine Werbepause ein (AWS-CLI):

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

Nach erfolgreicher Rückgabe von InsertAdBreak können Sie ein EventBridge-Ereignis (IVS Ad Break State Change) mit einem Zeitstempel empfangen, der angibt, wann die Werbepause voraussichtlich in die Zuschauer-Wiedergabelisten eingefügt wird. Das ist der Zeitpunkt, zu dem der Broadcaster davon ausgehen kann, dass Werbung die Inhalte ersetzt. Wenn keine Werbung eingeblendet werden kann (beispielsweise wenn der Ad Decision Server keine Werbung zurückgibt oder die Werbung von MediaTailor transkodiert werden muss), wird stattdessen der Quellinhalt angezeigt.

EventBridge-Integration

Bei SSAI wird das Ereignis IVS Ad Break State Change (mit der Bezeichnung „Ad Break Inserted“) hinzugefügt, das folgende Felder enthält:

7. Schritt: Player-SDK-Ereignisse

Für alle Plattformen gibt das Player-SDK Ereignisse aus, wenn eine Werbepause wiedergegeben wird, und meldet, wann Werbung startet, läuft und endet. Nachfolgend finden Sie eine allgemeine Übersicht über die verfügbaren Ereignisse und die jeweiligen Zeitpunkte:

Die jeweiligen Namen der Ereignisse und Nutzdaten für die einzelnen Plattformen finden Sie in der Dokumentation zum Player-SDK:

Nachfolgend finden Sie ein Beispiel dafür, wie Sie mithilfe von Werbeereignissen im Web-SDK eine einfache UI-Komponente zum Werbe-Countdown während einer Werbepause erstellen:

// 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(); 
});

Werbemarkierungen in aufgezeichneten Inhalten

Wenn ein Live-Stream mithilfe der automatischen Aufzeichnung in Amazon S3 aufgezeichnet wird, erstellt IVS eine VOD-Wiedergabeliste und schreibt diese in S3. Diese enthält SCTE-35-Werbemarkierungen an den Stellen, an denen während des Live-Streams Werbung ausgelöst wurde. Details dazu finden Sie unter SSAI-Wiedergabeliste – Referenz.

Zuschauererlebenis

Wenn Sie eine Werbepause einfügen, blendet MediaTailor standardmäßig Werbung für alle Zuschauer ein. Wenn Sie für Streams Token zur Wiedergabeautorisierung nutzen, können Sie Zuschauer vom Empfang von Werbung ausschließen, indem Sie dem JWT-Token zur Wiedergabeautorisierung den Claim "aws:ads-opt-out": true hinzufügen.

Beginnen Zuschauer mitten in einer Werbepause mit dem Streaming, rundet IVS die Dauer der Werbepause auf das nächste Viertel auf. Beispiel: Ein Zuschauer, der 35 Sekunden vor Ende einer 60-sekündigen Werbepause hinzukommt, sieht eine 45-sekündige Werbepause.

Wenn Sie die Wiedergabekonfiguration für MediaTailor aktualisieren oder neue Werbung hinzufügen, sehen die Zuschauer bei der ersten Anforderung einer Werbepause möglicherweise keine Werbung, da MediaTailor die Werbung zuerst transkodieren muss. Nach einigen Minuten führen nachfolgende Aufrufe von InsertAdBreak dazu, dass die Zuschauer Werbung sehen. Diese Transcodes werden in den Transcode-Protokollen von MediaTailor aufgezeichnet.

Parameter für die Zuschauerverfolgung

Beim Konfigurieren eines Ad Decisioning Servers (ADS) in der Wiedergabekonfiguration für Elemental MediaTailor können Sie mithilfe von Vorlagen Parameter an den ADS übergeben (siehe MediaTailor – Übergeben von Parametern an den ADS). Bei IVS-SSAI können Sie Parameter für jeden Zuschauer übergeben, und zwar mithilfe des Tokens zur Wiedergabeautorisierung für den jeweiligen Benutzer. Dazu fügen Sie einen Claim mit dem folgenden Format hinzu:

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

Diese Parameter werden an Elemental MediaTailor übergeben, um als Vorlagenvariablen [player_params.key1] und [player_params.key2] ausgefüllt zu werden. Schlüssel, die Sie in diese Liste einfügen, haben immer die Vorlagenparameter player_params als Namespace.

Die Gesamtgröße der Nutzdaten für alle Schlüssel und Werte zusammen ist auf 1 000 Byte begrenzt.

Berichtsmodus

Wenn ein Zuschauer Werbung sieht, kann der Client oder Server Beacons senden, die den Wiedergabefortschritt der einzelnen Werbemittel anzeigen. Standardmäßig verarbeitet MediaTailor das Beaconing auf der Serverseite. Den Berichtsmodus können Sie steuern, indem Sie dem Token zur Wiedergabeautorisierung den folgenden Claim hinzufügen:

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

Der Standardwert ist SERVER. Bei der Einstellung SERVER sendet MediaTailor Beacons auf der Serverseite. Bei der Einstellung CLIENT ist serverseitiges Beaconing deaktiviert und die Tracking-Daten werden im Feld metadata.trackingData des Ereignisses adBreakStarted des IVS-Player-SDK bereitgestellt. Das IVS-Player-SDK ruft keine Beacon-URLs auf.

Bekannte Probleme

SSAI-Wiedergabeliste – Referenz

Live-Varianten-Wiedergabeliste mit SSAI

Wenn Werbung in den Stream eingefügt wird, fügt IVS die unten dokumentierten Tags vor den Werbesegmenten ein.

1. Deklaration der eingefügten Werbung

#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. Änderung der Streamquelle

#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. Markierung für Diskontinuität

#EXT-X-DISCONTINUITY

Standard-HLS-Tag, das signalisiert, dass sich die Kodierungsparameter zwischen dem Live-Stream und dem Werbeninhalt ändern können.

Werbesegmente

#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-Varianten-Wiedergabeliste mit SSAI

Wenn ein Live-Stream aufgezeichnet wird, erstellt IVS eine VOD-Wiedergabeliste und schreibt diese in S3. Diese enthält SCTE-35-Werbemarkierungen an den Stellen, an denen während des Live-Streams Werbung ausgelöst wurde. Um Werbung während der VOD-Wiedergabe einzublenden, stellen Sie diese IVS-Wiedergabeliste über MediaTailor bereit, das für das Einfügen der Werbesegmente in die Wiedergabeliste zuständig ist. MediaTailor ersetzt die ursprünglichen VOD-Segmente während der Werbepause durch Werbesegmente.

1. Markierung für den Start der Werbepause (SCTE35-OUT)

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

2. Werbesegmente (von MediaTailor eingefügt)

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

3. Markierung für das Ende der Werbepause (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