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

1. Übersicht

In diesem Codelab wird beschrieben, wie Sie eine benutzerdefinierte Web Receiver-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 ihr Mobilgerät dann 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 basierend auf der Google Cast-Design-Checkliste hinzufügen.

Die Google Cast-Design-Checkliste soll die Cast-Implementierungen standardisieren, damit die Nutzer auf allen unterstützten Plattformen eine intuitive Bedienung erwarten können.

Ziele

Nach Abschluss dieses Codelabs haben Sie einen Cast-Receiver erstellt, der die Break API nutzt.

Lerninhalte

• VMAP- und VAST-Unterbrechungen in Cast-Inhalte einfügen
• Pausenclips überspringen
• Standardverhalten bei Pausen beim Suchen anpassen

Voraussetzungen

• Die aktuelle Version des Browsers Google Chrome.
• Ein HTTPS-Hostingdienst wie Firebase Hosting oder ngrok.
• Ein Google Cast-Gerät wie ein Chromecast oder Android TV, das für den Internetzugriff konfiguriert ist.
• Einen Fernseher oder Monitor mit HDMI-Eingang oder einen Google Home Hub

Erfahrung

Bevor Sie mit diesem Codelab fortfahren, sollten Sie die folgenden Kenntnisse haben.

• Allgemeine Kenntnisse in der Webentwicklung.
• Cast Web Receiver-Anwendungen erstellen

> Probleme mit dem Netzwerk? > Wenn Sie sich an einem Ort befinden, an dem das WLAN nicht zuverlässig ist, kann der Chromecast über einen Ethernet-Adapter für

Chromecast oder Chromecast mit Google TV.

Wie werden Sie diese Anleitung verwenden?

Nur lesen Lesen und Übungen durchführen

Wie würden Sie Ihre Erfahrung mit der Entwicklung von Web-Apps bewerten?

Anfänger Mittelstufe Fortgeschritten

2. Beispielcode abrufen

Laden Sie den gesamten Beispielcode auf Ihren Computer herunter…

Quellcode herunterladen

und entpacken Sie die heruntergeladene ZIP-Datei.

> Das Codelab-Repository „cast-videos-cast“ enthält zwei Beispielprojekte: > * app-start: Der Startcode, auf dem Sie in diesem Codelab aufbauen. * app-done: Der vollständige Code der fertigen Beispiel-Video-App.

3. Empfänger lokal bereitstellen

Damit du deinen Web Receiver mit einem Google Cast-Gerät verwenden kannst, muss er an einem Ort gehostet werden, an dem dein Google Cast-Gerät ihn erreichen kann. Wenn Sie bereits einen Server haben, der HTTPS unterstützt, überspringen Sie die folgenden Anweisungen 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 haben noch kein Cast-Entwicklerkonto? > Registrieren Sie sich für ein Konto in der Google Cast SDK Developer Console und zahlen Sie die Registrierungsgebühr.

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

Klicken Sie auf „Neue Anwendung hinzufügen“.

Wählen Sie „Benutzerdefinierter Receiver“ aus. Das ist der Receiver, den wir erstellen.

Gib die Details zu deinem neuen Empfänger ein. Verwenden Sie die URL, unter der Sie Ihre Web Receiver-Anwendung hosten möchten. Notieren Sie sich die Anwendungs-ID, die von der Console generiert wird, sobald Sie die Anwendung registrieren. Die Senderanwendung 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 auf Ihre Receiver-Anwendung zugreifen kann, bevor Sie sie veröffentlichen. 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 unveröffentlichten Empfängeranwendung zu arbeiten.

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

Gib die Seriennummer ein, die auf der Rückseite deines Cast-Geräts aufgedruckt ist, und gib dem Gerät einen aussagekräftigen Namen. Sie können die Seriennummer auch finden, indem Sie Ihren Bildschirm in Chrome spiegeln, 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 Tests bereit sind. Nach 5 bis 15 Minuten musst du dein Cast-Gerät neu starten.

5. Startprojekt vorbereiten

Bevor Sie mit diesem Codelab beginnen, sollten Sie sich den Entwicklerleitfaden für Anzeigen ansehen, in dem die APIs für Werbeunterbrechungen beschrieben werden.

Die Unterstützung für Google Cast muss der heruntergeladenen Start-App hinzugefügt werden. Hier sind einige Google Cast-Begriffe, die in diesem Codelab verwendet werden:

• Eine Absender-App wird auf einem Mobilgerät oder Laptop ausgeführt.
• Auf dem Google Cast-Gerät wird eine Receiver-App ausgeführt.

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

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

Die von Ihnen ausgewählte Webhostinglösung sollte mit den vorgenommenen Änderungen aktualisiert werden. Achten Sie darauf, dass Sie die Änderungen an die Hostwebsite übertragen, wenn Sie sie weiterhin validieren und testen.

App-Design

Wie bereits erwähnt, wird im Codelab eine Senderanwendung zum Starten einer Cast-Sitzung und eine Empfängeranwendung verwendet, die so geändert wird, dass die APIs für Werbeunterbrechungen verwendet werden.

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

Hinweis: Wenn das Cast-Symbol nicht angezeigt wird, prüfen Sie, ob der Web Receiver und die Cast-Geräte ordnungsgemäß in der Cast Developer Console registriert sind. Falls noch nicht geschehen, schalte alle gerade registrierten Cast-Geräte aus und wieder ein.

Die Receiver-App ist der Schwerpunkt dieses Codelabs und besteht aus einer Hauptansicht, die in index.html definiert ist, und einer JavaScript-Datei namens js/receiver.js. Diese werden unten genauer beschrieben.

index.html

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

receiver.js

Dieses Skript enthält die gesamte Logik für unsere Receiver-App. Derzeit enthält es einen einfachen CAF-Receiver zum Initialisieren des Cast-Kontexts und zum Laden eines Video-Assets bei der Initialisierung. Außerdem wurden einige Debug-Logger-Funktionen hinzugefügt, um Protokollierungsinformationen an das Cast and Command-Tool zurückzugeben.

> Cast-Dokumentation? > Wir haben eine umfassende Dokumentation für Empfänger, iOS-, Android- und Chrome-Absender.

6. VMAP-Anweisungen zu Inhalten hinzufügen

Das Cast Web Receiver SDK unterstützt Anzeigen, die über Digital Video Multiple Ad Playlists (VMAP) angegeben werden. Die XML-Struktur gibt die Werbeunterbrechungen eines Mediums und die zugehörigen Metadaten für Unterbrechungsclips 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. Sie enthält ein Beispiel für die VMAP-Tag-URL von DoubleClick und einen zufälligen Correlator-Wert, damit 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. Starte eine Cast-Sitzung im Tool für Cast und Befehle, indem du auf das Cast-Symbol klickst. Die VMAP-Anzeigen sollten vor dem Hauptinhalt ausgeliefert werden.

7. VAST-Tags zu 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 Integration von VAST-Anzeigen (Video Ad Serving Template) verfügbar sind. Wenn Sie den VMAP-Code aus dem vorherigen Abschnitt implementiert haben, kommentieren Sie ihn aus.

Kopieren Sie Folgendes in Ihre js/receiver.js-Datei nach dem Load Request Interceptor. Sie enthält sechs VAST-Break-Clips von DoubleClick und einen zufälligen Correlator-Wert. Diese Pausenclips sind 5 Pausen zugewiesen. Die position jeder Unterbrechung wird auf eine Zeit in Sekunden relativ zum Hauptinhalt festgelegt, einschließlich Pre-Roll-Unterbrechungen (position auf 0 festgelegt) und Post-Roll-Unterbrechungen (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 Pause ist ein Array. Das bedeutet, dass jeder Pause mehrere Pausenclips zugewiesen werden können.

Suchen Sie in Ihrer js/receiver.js file-Datei nach dem LOAD-Nachrichten-Interceptor und ersetzen Sie ihn durch den folgenden Code. Beachten Sie, dass die VMAP-Arbeit auskommentiert ist, um VAST-Anzeigen zu demonstrieren.

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. Starte eine Cast-Sitzung im Tool für Cast und Befehle, indem du auf das Cast-Symbol klickst. Die VAST-Anzeigen sollten vor dem Hauptinhalt abgespielt werden.

8. Überspringen von Werbeunterbrechungen

CAF bietet eine Klasse namens BreakManager, mit der Sie benutzerdefinierte Geschäftsregeln für das Anzeigenverhalten implementieren können. Mit einer dieser Funktionen können Anwendungen Pausen und Pausenclips basierend auf einer bestimmten Bedingung programmatisch überspringen. In diesem Beispiel wird gezeigt, wie eine Werbeunterbrechung übersprungen wird, deren Position innerhalb der ersten 30 Sekunden des Inhalts liegt, aber nicht die Post-Roll-Unterbrechungen. Bei den im vorherigen Abschnitt konfigurierten VAST-Anzeigen sind fünf Pausen definiert: eine Pre-Roll-Pause, drei Mid-Roll-Pausen (bei 15, 60 und 100 Sekunden) und eine Post-Roll-Pause. Nachdem Sie die Schritte ausgeführt haben, 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 Unterbrechen des Ladevorgangs festzulegen. Kopieren Sie die folgende Zeile in Ihre js/receiver.js-Datei, nach den Zeilen mit den Variablen context und playerManager, um einen Verweis auf die Instanz zu erhalten.

const breakManager = playerManager.getBreakManager();

Die Anwendung sollte einen Interceptor mit einer Regel einrichten, um alle Werbeunterbrechungen zu ignorieren, die vor 30 Sekunden auftreten. Dabei sollten alle Post-Roll-Unterbrechungen berücksichtigt werden, da ihre position-Werte -1 sind. Dieser Interceptor funktioniert wie der LOAD-Interceptor auf PlayerManager, ist jedoch speziell für das Laden von Unterbrechungsclips vorgesehen. Legen Sie dies nach dem LOAD-Anfrage-Interceptor 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 ein Break keine Pausenclips definiert sind, wird die Pause übersprungen.

Speichern Sie die Änderungen in js/receiver.js und laden Sie die Datei auf Ihren Webserver hoch. Starte eine Cast-Sitzung im Tool für Cast und Befehle, indem du auf das Cast-Symbol klickst. Die VAST-Anzeigen sollten verarbeitet werden. Die Pre-Roll-Anzeige und die erste Mid-Roll-Anzeige (deren position 15 Sekunden beträgt) werden nicht ausgeliefert.

9. Verhalten beim Suchen in Pausen anpassen

Bei der Suche nach Pausen werden in der Standardimplementierung alle Break-Elemente abgerufen, deren Position zwischen den Werten seekFrom und seekTo des Suchvorgangs liegt. Aus dieser Liste von Pausen spielt das SDK die Break ab, deren position dem Wert seekTo am nächsten ist und deren isWatched-Attribut auf false festgelegt ist. Die Eigenschaft von isWatched wird dann auf true festgelegt und der Player beginnt mit der Wiedergabe der Pausenclips. Nachdem die Unterbrechung angesehen wurde, wird die Wiedergabe des Hauptinhalts ab der Position seekTo fortgesetzt. Wenn keine solche Unterbrechung vorhanden ist, wird keine Unterbrechung wiedergegeben und die Wiedergabe der Hauptinhalte wird an der Position seekTo fortgesetzt.

Mit der setBreakSeekInterceptor API in BreakManager können Sie anpassen, welche Pausen bei einem Seek abgespielt werden. Wenn eine Anwendung ihre benutzerdefinierte Logik über diese API bereitstellt, ruft das SDK sie auf, wenn ein Suchvorgang für eine oder mehrere Pausen ausgeführt wird. An die Callback-Funktion wird ein Objekt übergeben, das alle Unterbrechungen zwischen der Position seekFrom und der Position seekTo enthält. Die Anwendung muss dann die BreakSeekData ändern und zurückgeben.

Im folgenden Beispiel wird das Standardverhalten überschrieben, indem alle Pausen berücksichtigt werden, zu denen gesucht wurde, und nur die erste Pause wiedergegeben wird, die auf der Zeitachse angezeigt wird.

Kopieren Sie Folgendes in Ihre js/receiver.js-Datei unter die Definition für 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 oder null zurückgibt, werden keine Pausen eingelegt.

Speichern Sie die Änderungen in js/receiver.js und laden Sie die Datei auf Ihren Webserver hoch. Starte eine Cast-Sitzung im Tool für Cast und Befehle, indem du auf das Cast-Symbol klickst. Die VAST-Anzeigen sollten verarbeitet werden. Die Pre-Roll-Anzeige und die erste Mid-Roll-Anzeige (deren position 15 Sekunden beträgt) werden nicht ausgeliefert.

Warte, bis die Wiedergabezeit 30 Sekunden erreicht hat, damit alle Pausen übersprungen werden, die vom Break-Clip-Lade-Interceptor übersprungen werden. Wenn Sie die gewünschte Stelle erreicht haben, können Sie einen Suchbefehl senden, indem Sie den Tab Media Control (Mediensteuerung) aufrufen. Geben Sie 300 Sekunden in das Feld In Media suchen ein und klicken Sie auf die Schaltfläche BIS. Sehen Sie sich die Logs an, die im Break Seek Interceptor ausgegeben werden. Das Standardverhalten sollte jetzt überschrieben werden, damit die Pause näher am Zeitpunkt seekFrom eingelegt wird.

10. Glückwunsch

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

Weitere Informationen finden Sie im Entwicklerleitfaden zu Werbeunterbrechungen.

> Weitere Cast-Funktionen > Sehen Sie sich die anderen Cast-Codelabs und unsere Beispiel-Apps auf GitHub an.