Unterstützung der Ad Breaks API zu einem Web-Empfänger hinzufügen

1. Übersicht

Google Cast-Logo

In diesem Codelab erfahren Sie, wie Sie eine benutzerdefinierte Webempfänger-App erstellen, die die Cast Ad Breaks API verwendet.

Was ist Google Cast?

Mit Google Cast können Nutzer Inhalte von einem Mobilgerät auf einen Fernseher streamen. Nutzer können dann ihr Mobilgerät als Fernbedienung für die Medienwiedergabe auf dem Fernseher verwenden.

Mit dem Google Cast SDK können Sie Ihre App erweitern, um einen Fernseher oder ein Soundsystem zu steuern. Mit dem Cast SDK können Sie die erforderlichen UI-Komponenten gemäß der Checkliste für das Google Cast-Design hinzufügen.

Die Google Cast-Design-Checkliste dient dazu, Cast-Implementierungen zu standardisieren, damit die Nutzung auf allen unterstützten Plattformen intuitiv ist.

Ziele

Wenn du dieses Codelab abgeschlossen hast, hast du einen Cast-Empfänger erstellt, der die Break API nutzt.

Lerninhalte

  • VMAP- und VAST-Werbeunterbrechungen in Inhalten für Google Cast einfügen
  • Werbeunterbrechungsclips überspringen
  • Standardverhalten von Werbeunterbrechungen beim Suchen anpassen

Voraussetzungen

Erfahrung

Sie sollten die folgenden Voraussetzungen erfüllen, bevor Sie mit diesem Codelab fortfahren.

  • Allgemeines Wissen über die Webentwicklung.
  • Web-Empfängeranwendungen für Google Cast erstellen

Wie möchten Sie diese Anleitung verwenden?

Nur durchlesen Durchlesen und die Übungen absolvieren

Wie würden Sie Ihre Erfahrungen mit der Erstellung von Web-Apps bewerten?

Anfänger Mittelstufe Fortgeschritten

2. Beispielcode abrufen

Laden Sie den gesamten Beispielcode auf Ihren Computer herunter…

und entpacken Sie die heruntergeladene ZIP-Datei.

3. Empfänger lokal bereitstellen

Damit du deinen Webreceiver mit einem Cast-Gerät verwenden kannst, muss er an einem Ort gehostet werden, an dem dein Cast-Gerät ihn erreichen kann. Falls Sie bereits einen Server haben, der HTTPS unterstützt, überspringen Sie die folgende Anleitung und notieren Sie sich die URL, da Sie sie im nächsten Abschnitt benötigen.

Wenn Sie keinen Server zur Verfügung haben, können Sie Firebase Hosting oder ngrok verwenden.

Server ausführen

Nachdem Sie den gewünschten Dienst eingerichtet haben, rufen Sie app-start auf und starten Sie den Server.

Notieren Sie sich die URL für Ihren gehosteten Empfänger. Sie benötigen sie im nächsten Abschnitt.

4. Anwendung in der Cast Developer Console registrieren

Sie müssen Ihre Anwendung registrieren, um einen benutzerdefinierten Empfänger wie in diesem Codelab auf Chromecast-Geräten ausführen zu können. Nachdem Sie Ihre Anwendung registriert haben, wird eine Anwendungs-ID generiert, die zum Starten der Web Receiver-Anwendung konfiguriert werden muss.

Bild der Google Cast SDK Developer Console mit hervorgehobener Schaltfläche „Add New Application“ (Neue Anwendung hinzufügen)

Klicken Sie auf „Neue Anwendung hinzufügen“.

Bild des Bildschirms „Neue Empfängeranwendung“, auf dem die Option „Benutzerdefinierter Empfänger“ hervorgehoben ist

Wählen Sie „Benutzerdefinierter Empfänger“ aus.

Bild des Bildschirms „Neuer benutzerdefinierter Empfänger“ mit einer URL, die jemand in das Feld „URL der Empfängeranwendung“ eingibt

Gib die Details deines neuen Empfängers ein. Achten Sie darauf, die URL zu verwenden, die auf den Ort verweist, an dem Sie Ihre Web Receiver-Anwendung hosten möchten. Notieren Sie sich die Anwendungs-ID, die von der Console generiert wird, sobald Sie die Anwendung registriert haben. Die Absenderanwendung wird in einem späteren Abschnitt so konfiguriert, dass sie diese Kennung verwendet.

Außerdem müssen Sie ein Google Cast-Gerät registrieren, damit es vor der Veröffentlichung auf Ihre Empfängeranwendung zugreifen kann. Sobald Sie Ihre Empfängeranwendung veröffentlicht haben, ist sie für alle Google Cast-Geräte verfügbar. Für dieses Codelab wird empfohlen, mit einer nicht veröffentlichten Empfängeranwendung zu arbeiten.

Bild der Google Cast SDK Developer Console mit der hervorgehobenen Schaltfläche „Add New Device“ (Neues Gerät hinzufügen)

Klicken Sie auf „Neues Gerät hinzufügen“.

Bild des Dialogfelds „Streamingempfängergerät hinzufügen“

Geben Sie die Seriennummer ein, die auf der Rückseite Ihres Übertragungsgeräts aufgedruckt ist, und geben Sie einen aussagekräftigen Namen ein. Sie können die Seriennummer auch finden, indem Sie Ihren Bildschirm in Chrome streamen, wenn Sie auf die Google Cast SDK Developer Console zugreifen.

Es dauert 5 bis 15 Minuten, bis der Empfänger und das Gerät für den Test bereit sind. Warten Sie 5 bis 15 Minuten und starten Sie dann Ihr Streaminggerät neu.

5. Startprojekt vorbereiten

Bevor du mit diesem Codelab beginnst, solltest du dir den Entwicklerleitfaden für YouTube-Anzeigen ansehen. Dort findest du eine Übersicht über die APIs für Werbeunterbrechungen.

Der von Ihnen heruntergeladenen Start-App muss Google Cast-Support hinzugefügt werden. Hier sind einige Google Cast-Begriffe, die in diesem Codelab verwendet werden:

  • eine Sender-App auf einem Mobilgerät oder Laptop ausgeführt wird,
  • eine Empfänger-App auf dem Google Cast-Gerät ausgeführt wird.

Jetzt können Sie mit Ihrem bevorzugten Texteditor auf dem Starterprojekt aufbauen:

  1. Wählen Sie das Verzeichnis Ordnersymbolapp-start aus dem Download des Beispielcodes aus.
  2. Öffnen Sie js/receiver.js und index.html.

Hinweis: Während Sie dieses Codelab durcharbeiten, sollten Sie die von Ihnen ausgewählte Webhosting-Lösung mit den vorgenommenen Änderungen aktualisieren. Achten Sie darauf, dass Sie die Änderungen an die Host-Website übertragen, wenn Sie sie weiter validieren und testen.

App-Design

Wie bereits erwähnt, verwendet das Codelab eine Senderanwendung, um eine Übertragungssitzung zu initiieren, und eine Empfängeranwendung, die so geändert wird, dass sie die APIs für Werbeunterbrechungen verwendet.

In diesem Codelab dient das Cast and Command Tool als Websender, um die Empfänger-App zu starten. Öffnen Sie das Tool zuerst in einem Chrome-Browser. Geben Sie die Empfänger-App-ID ein, die Sie in der Cast SDK Developer Console erhalten haben, und klicken Sie auf Festlegen, um die Sender-App für den Test zu konfigurieren.

Hinweis: Wenn das Streamingsymbol nicht angezeigt wird, prüfen Sie, ob der Webempfänger und die Streaminggeräte in der Cast Developer Console richtig registriert sind. Schalten Sie alle gerade registrierten Streaminggeräte aus und wieder ein.

Die Empfänger-App steht im Mittelpunkt dieses Codelabs und besteht aus einer in index.html definierten Hauptansicht und einer JavaScript-Datei namens js/receiver.js. Diese werden im Folgenden näher beschrieben.

index.html

Diese HTML-Datei enthält die Benutzeroberfläche für unsere Empfänger-App, die vom Element cast-media-player bereitgestellt wird. Außerdem werden das CAF SDK und die Cast Debug Logger-Bibliotheken geladen.

receiver.js

Dieses Script verwaltet die gesamte Logik für unsere Empfänger-App. Derzeit enthält es einen einfachen CAF-Empfänger, um den Übertragungskontext zu initialisieren und bei der Initialisierung ein Video-Asset zu laden. Außerdem wurden einige Funktionen zur Fehlerbehebung hinzugefügt, um eine erneute Protokollierung in das Cast- und Command-Tool zu ermöglichen.

6. VMAP zu deinen Inhalten hinzufügen

Das Cast Web Receiver SDK unterstützt Anzeigen, die über Digital Video Multiple Ad Playlists (auch VMAP genannt) angegeben werden. Die XML-Struktur gibt die Werbeunterbrechungen eines Mediums und die zugehörigen Metadaten für Werbeclips an. Zum Einfügen dieser Anzeigen stellt das SDK das Attribut vmapAdsRequest im MediaInformation-Objekt bereit.

Erstellen Sie in der Datei js/receiver.js ein VastAdsRequest-Objekt. Suchen Sie die Funktion LOAD request interceptor und ersetzen Sie sie durch den folgenden Code. Es enthält eine Beispiel-VMAP-Tag-URL von DoubleClick und einen zufälligen correlator-Wert, um sicherzustellen, dass bei nachfolgenden Anfragen an dieselbe URL eine XML-Vorlage mit noch nicht angesehenen Werbeunterbrechungen generiert wird.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      const vmapUrl =
          'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
          Math.floor(Math.random() * Math.pow(10, 10));
      let vmapRequest = new cast.framework.messages.VastAdsRequest();
      vmapRequest.adTagUrl = vmapUrl;
      loadRequestData.media.vmapAdsRequest = vmapRequest;

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

Speichern Sie die Änderungen in js/receiver.js und laden Sie die Datei auf Ihren Webserver hoch. Starten Sie eine Übertragungssitzung im Übertragungs- und Befehlstool, indem Sie auf das Übertragungssymbol klicken. Die VMAP-Anzeigen sollten abgespielt werden, gefolgt vom Hauptinhalt.

7. VAST-Anzeigen zu deinen Inhalten hinzufügen

Wie bereits erwähnt, werden im Web Receiver SDK viele Arten von Anzeigen unterstützt. In diesem Abschnitt werden die APIs beschrieben, die für die Einbindung von Digital Video Ad Serving Template-Anzeigen (VAST) verfügbar sind. Wenn Sie den VMAP-Code aus dem vorherigen Abschnitt implementiert haben, kommentieren Sie ihn aus.

Fügen Sie den folgenden Code nach dem Interceptor für Ladeanfragen in die js/receiver.js-Datei ein. Es enthält sechs VAST-Pausenclips von DoubleClick und einen zufälligen Korrelator-Wert. Diese Clips sind fünf Pausen zugewiesen. Für jede Werbeunterbrechung wird position auf eine Zeit in Sekunden relativ zum Hauptinhalt festgelegt, einschließlich Pre-Roll- (position auf 0 festgelegt) und Post-Roll-Werbeunterbrechungen (position auf -1 festgelegt).

const addVASTBreaksToMedia = (mediaInformation) => {
  mediaInformation.breakClips = [
    {
      id: 'bc1',
      title: 'bc1 (Pre-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('preroll')
      }
    },
    {
      id: 'bc2',
      title: 'bc2 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc3',
      title: 'bc3 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc4',
      title: 'bc4 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc5',
      title: 'bc5 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc6',
      title: 'bc6 (Post-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('postroll')
      }
    }
  ];

  mediaInformation.breaks = [
    {id: 'b1', breakClipIds: ['bc1'], position: 0},
    {id: 'b2', breakClipIds: ['bc2'], position: 15},
    {id: 'b3', breakClipIds: ['bc3', 'bc4'], position: 60},
    {id: 'b4', breakClipIds: ['bc5'], position: 100},
    {id: 'b5', breakClipIds: ['bc6'], position: -1}
  ];
};

Hinweis:Das Attribut breakClipIds einer Werbeunterbrechung ist ein Array. Das bedeutet, dass jeder Werbeunterbrechung mehrere Werbeunterbrechungsclips zugewiesen werden können.

Suchen Sie in js/receiver.js file nach dem LOAD-Nachrichten-Interceptor und ersetzen Sie ihn durch den folgenden Code. Hinweis: Der VMAP-Code ist kommentiert, um Anzeigen vom Typ „VAST“ zu zeigen.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      // const vmapUrl =
      //     'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
      //     Math.floor(Math.random() * Math.pow(10, 10));
      // let vmapRequest = new cast.framework.messages.VastAdsRequest();
      // vmapRequest.adTagUrl = vmapUrl;
      // loadRequestData.media.vmapAdsRequest = vmapRequest;

      // Append VAST ad breaks to the MediaInformation.
      addVASTBreaksToMedia(loadRequestData.media);

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

Speichern Sie die Änderungen in js/receiver.js und laden Sie die Datei auf Ihren Webserver hoch. Starten Sie das Streaming über das Streaming- und Kommandotool, indem Sie auf das Cast-Symbol klicken. Die VAST-Anzeigen sollten gefolgt vom Hauptcontent wiedergegeben werden.

8. Überspringen von Werbeunterbrechungen

CAF hat eine Klasse namens BreakManager, die Sie bei der Implementierung benutzerdefinierter Geschäftsregeln für Anzeigenverhalten unterstützt. Mit einer dieser Funktionen können Anwendungen Pausen und Clips programmatisch basierend auf einer bestimmten Bedingung überspringen. In diesem Beispiel wird gezeigt, wie eine Werbeunterbrechung übersprungen wird, deren Position sich innerhalb der ersten 30 Sekunden des Contents befindet, nicht aber die Post-Roll. Bei Verwendung der im vorherigen Abschnitt konfigurierten VAST-Anzeigen sind fünf Werbeunterbrechungen definiert: eine Pre-Roll-Pause, drei Mid-Roll-Werbeunterbrechungen (bei 15, 60 und 100 Sekunden) und eine Post-Roll-Pause. Danach werden nur die Pre-Rolls und Mid-Rolls übersprungen, deren Position bei 15 Sekunden liegt.

Dazu sollte die Anwendung APIs aufrufen, die über BreakManager verfügbar sind, um einen Interceptor für das Laden von Werbeunterbrechungen festzulegen. Fügen Sie die folgende Zeile in die Datei js/receiver.js nach den Zeilen mit den Variablen context und playerManager ein, um einen Verweis auf die Instanz zu erhalten.

const breakManager = playerManager.getBreakManager();

Die Anwendung sollte einen Interceptor mit einer Regel einrichten, um Werbeunterbrechungen zu ignorieren, die vor 30 Sekunden auftreten. Post-Roll-Unterbrechungen müssen dabei berücksichtigt werden, da ihre position-Werte -1 sind. Dieser Interceptor funktioniert wie der LOAD-Interceptor bei PlayerManager, mit der Ausnahme, dass er speziell für das Laden von Unterbrechungsclips vorgesehen ist. Legen Sie diesen Wert nach dem LOAD-Anfrage-Abfangmechanismus und vor der addVASTBreaksToMedia-Funktionsdeklaration fest.

Kopieren Sie Folgendes in die Datei js/receiver.js.

breakManager.setBreakClipLoadInterceptor((breakClip, breakContext) => {
  /**
   * The code will skip playback of break clips if the break position is within
   * the first 30 seconds.
   */
  let breakObj = breakContext.break;
  if (breakObj.position >= 0 && breakObj.position < 30) {
    castDebugLogger.debug(
        'MyAPP.LOG',
        'Break Clip Load Interceptor skipping break with ID: ' + breakObj.id);
    return null;
  } else {
    return breakClip;
  }
});

Hinweis: Wenn Sie hier null zurückgeben, wird die Verarbeitung von BreakClip übersprungen. Wenn für eine Break keine Werbeunterbrechungsclips definiert sind, wird die Werbeunterbrechung übersprungen.

Speichern Sie die Änderungen in js/receiver.js und laden Sie die Datei auf Ihren Webserver hoch. Starten Sie eine Übertragungssitzung im Übertragungs- und Befehlstool, indem Sie auf das Übertragungssymbol klicken. Die VAST-Anzeigen sollten verarbeitet werden. Die Pre-Roll- und die erste Mid-Roll-Anzeige (deren position 15 Sekunden beträgt) werden nicht wiedergegeben.

9. Verhalten bei der Suche nach Werbeunterbrechungen anpassen

Bei der Suche nach Werbeunterbrechungen werden mit der Standardimplementierung alle Break-Elemente abgerufen, deren Position zwischen den Werten seekFrom und seekTo des Suchvorgangs liegt. Aus dieser Liste von Unterbrechungen gibt das SDK den Break wieder, dessen position dem Wert seekTo am nächsten ist und dessen Attribut isWatched auf false gesetzt ist. Die Eigenschaft isWatched dieser Werbeunterbrechung wird dann auf true gesetzt und der Player beginnt mit der Wiedergabe der Pausenclips. Nach der Werbeunterbrechung wird die Wiedergabe des Hauptinhalts an der Position seekTo fortgesetzt. Ist keine solche Pause vorhanden, wird keine Pause abgespielt und die Wiedergabe des Hauptinhalts wird an der Position seekTo fortgesetzt.

Zum Anpassen der Pausen bei einer Suche stellt das Cast SDK die setBreakSeekInterceptor API in BreakManager bereit. Wenn eine Anwendung ihre benutzerdefinierte Logik über diese API bereitstellt, wird sie vom SDK jedes Mal aufgerufen, wenn ein Suchvorgang über eine oder mehrere Werbeunterbrechungen hinweg ausgeführt wird. Der Callback-Funktion wird ein Objekt übergeben, das alle Unterbrechungen zwischen der seekFrom-Position und der seekTo-Position enthält. Die Anwendung muss dann die BreakSeekData ändern und zurückgeben.

Im folgenden Beispiel wird das Standardverhalten überschrieben, indem alle Werbeunterbrechungen, die übersprungen wurden, berücksichtigt und nur die erste Werbeunterbrechung abgespielt wird, die in der Zeitleiste angezeigt wird.

Kopieren Sie den folgenden Code in die Datei js/receiver.js unter der Definition in den setBreakClipLoadInterceptor.

breakManager.setBreakSeekInterceptor((breakSeekData) => {
  /**
   * The code will play an unwatched break between the seekFrom and seekTo
   * position. Note: If the position of a break is less than 30 then it will be
   * skipped due to the setBreakClipLoadInterceptor code.
   */
  castDebugLogger.debug(
      'MyAPP.LOG',
      'Break Seek Interceptor processing break ids ' +
          JSON.stringify(breakSeekData.breaks.map(adBreak => adBreak.id)));

  // Remove all other breaks except for the first one.
  breakSeekData.breaks.splice(1,breakSeekData.breaks.length);
  return breakSeekData;
});

Hinweis:Wenn die Funktion keinen Wert zurückgibt oder null zurückgibt, werden keine Werbeunterbrechungen wiedergegeben.

Speichern Sie die Änderungen in js/receiver.js und laden Sie die Datei auf Ihren Webserver hoch. Starten Sie eine Übertragungssitzung im Übertragungs- und Befehlstool, indem Sie auf das Übertragungssymbol klicken. Die VAST-Anzeigen sollten verarbeitet werden. Beachte, dass die Pre-Roll und die erste Mid-Roll (mit position 15 Sekunden) nicht abgespielt werden.

Warte, bis die Wiedergabezeit 30 Sekunden erreicht hat, um alle Unterbrechungen zu überwinden, die vom Interceptor zum Laden von Clips übersprungen werden. Rufe dann den Tab Media Control (Mediensteuerung) auf, um einen Suchbefehl zu senden. Gib in das Eingabefeld In Medien springen den Wert 300 Sekunden ein und klicke auf die Schaltfläche ZU. Notieren Sie sich die Protokolle, die im Break Seek Interceptor ausgegeben werden. Das Standardverhalten sollte jetzt überschrieben werden, damit die Unterbrechung näher an der Zeit von seekFrom wiedergegeben wird.

10. Glückwunsch

Sie wissen jetzt, wie Sie Ihrer Empfängeranwendung mit dem neuesten Cast Receiver SDK Anzeigen hinzufügen.

Weitere Informationen findest du im Entwicklerleitfaden zu Werbeunterbrechungen.