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

1. Überblick

Google Cast-Logo

In diesem Codelab erfährst du, wie du eine App für einen benutzerdefinierten Webempfänger erstellst, 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 anhand der Checkliste für das Google Cast-Design hinzufügen.

Die Checkliste für das Design von Google Cast dient zur Standardisierung von Cast-Implementierungen, damit die Nutzung auf allen unterstützten Plattformen intuitiv ist.

Ziele

Wenn Sie dieses Codelab abgeschlossen haben, haben Sie einen Cast Receiver erstellt, der die Break API nutzt.

Lerninhalte

  • VMAP- und VAST-Unterbrechungen in den Content für das Streamen einfügen
  • Pausenclips überspringen
  • Standardmäßige Werbeunterbrechung bei der Suche anpassen

Voraussetzungen

Plattform

Sie müssen die folgenden Anforderungen erfüllen, bevor Sie mit diesem Codelab fortfahren.

  • Allgemeines Wissen zur Webentwicklung
  • Cast Web Receiver-Anwendungen erstellen

Wie werden Sie dieses Tutorial verwenden?

Nur lesen Lesen und die Übungen abschließen

Wie würden Sie Ihre Erfahrungen mit der Entwicklung von Webanwendungen bewerten?

Neuling Fortgeschritten Profi

2. Beispielcode abrufen

Den gesamten Beispielcode auf Ihren Computer herunterladen...

und entpacken Sie die heruntergeladene ZIP-Datei.

3. Empfänger lokal bereitstellen

Damit Sie Ihren Webempfänger mit einem Übertragungsgerät verwenden können, muss es an einem Ort gehostet werden, an dem Ihr Übertragungsgerät eine Verbindung herstellen kann. Sollte Ihnen bereits ein Server zur Verfügung stehen, der HTTPS unterstützt, überspringen Sie die folgende Anleitung und merken Sie sich die URL, da Sie sie im nächsten Abschnitt benötigen.

Falls Ihnen kein Server zur Verfügung steht, können Sie Firebase Hosting oder ngrok verwenden.

Server ausführen

Nachdem Sie den Dienst Ihrer Wahl 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. Apps in der Cast-Entwicklerkonsole registrieren

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

Bild der Google Cast SDK Developer Console mit hervorgehobener Schaltfläche "Neue App hinzufügen"

Klicken Sie auf „Neue Anwendung hinzufügen“.

Screenshot des Bildschirms „New Receiver Application“ (Anwendung für neuen Empfänger), wobei die Option „Custom Receiver“ (Benutzerdefinierter Empfänger) hervorgehoben ist

Wählen Sie "Benutzerdefinierter Empfänger" aus.

Screenshot des Bildschirms "Neuer benutzerdefinierter Empfänger" mit einer URL, die jemand in das Feld "Anwendungs-URL des Empfängers" eingibt

Gib die Daten des neuen Empfängers ein. Achten Sie darauf, dass Sie die URL verwenden, die auf den Ort verweist, an dem Sie Ihre Web-Receiver-Anwendung hosten möchten. Notieren Sie die Anwendungs-ID, die nach der Registrierung der Anwendung von der Konsole generiert wird. Die Absenderanwendung wird in einem späteren Abschnitt zur Verwendung dieser ID konfiguriert.

Außerdem müssen Sie ein Google Cast-Gerät registrieren, damit es vor der Veröffentlichung auf Ihre Empfangs-App zugreifen kann. Nach der Veröffentlichung ist die Empfangs-App für alle Google Cast-Geräte verfügbar. Für dieses Codelab empfiehlt es sich, mit einer nicht veröffentlichten Empfängeranwendung zu arbeiten.

Bild der Google Cast SDK Developer Console mit hervorgehobener Schaltfläche "Neues Gerät hinzufügen"

Klicke auf „Neues Gerät hinzufügen“.

Bild des Dialogfelds "Cast Receiver-Gerät hinzufügen"

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

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 das Übertragungsgerät neu.

5. Startprojekt vorbereiten

Bevor Sie mit diesem Codelab beginnen, sollten Sie sich den Entwicklerleitfaden für Anzeigen ansehen, der eine Übersicht über die APIs für Werbeunterbrechungen enthält.

In der heruntergeladenen Start-App muss Google Cast unterstützt werden. Im Folgenden finden Sie einige Google Cast-Terminologie, die in diesem Codelab verwendet wird:

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

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

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

Hinweis: Die von Ihnen gewählte Webhosting-Lösung sollte mit den vorgenommenen Änderungen aktualisiert werden, während Sie dieses Codelab durcharbeiten. Stellen Sie sicher, dass Sie die Änderungen auf die Host-Website übertragen, wenn Sie mit der Validierung und dem Testen fortfahren.

App-Design

Wie bereits erwähnt, verwendet das Codelab eine Sender-App zum Initiieren einer Cast-Sitzung und eine Empfänger-App, die so geändert wird, dass die Werbeunterbrechungen-APIs verwendet werden.

In diesem Codelab fungiert das Cast- und Befehlszeilentool als Webabsender, um die Empfänger-App zu starten. Öffnen Sie dazu das Tool 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 Testzwecke zu konfigurieren.

Hinweis: Wenn Sie feststellen, dass das Cast-Symbol nicht angezeigt wird, vergewissern Sie sich, dass der Web-Receiver und die Übertragungsgeräte richtig in der Cast-Entwicklerkonsole registriert sind. Falls noch nicht geschehen, schalten Sie alle Übertragungsgeräte aus, die gerade registriert wurden, und schalten Sie sie aus.

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 unten näher beschrieben.

index.html

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

receiver.js

Dieses Skript verwaltet die gesamte Logik für unsere Empfänger-App. Derzeit enthält es einen grundlegenden CAF-Empfänger, um den Cast-Kontext zu initialisieren und nach der Initialisierung ein Video-Asset zu laden. Es wurden auch einige Funktionen des Fehlerbehebungsprotokolls hinzugefügt, um eine Rückprotokollierung im Cast- und Befehlstool zu ermöglichen.

6. VMAP zu 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 den Pausenclip an. Zum Einfügen dieser Anzeigen stellt das SDK die vmapAdsRequest-Eigenschaft im MediaInformation-Objekt bereit.

Erstellen Sie in der Datei js/receiver.js ein VastAdsRequest-Objekt. Suchen Sie die Funktion LOAD-Anfrageabfang und ersetzen Sie sie durch den folgenden Code. Es enthält eine Beispiel-URL für ein VMAP-Tag von DoubleClick und einen zufälligen correlator-Wert, damit nachfolgende Anfragen an dieselbe URL eine XML-Vorlage mit noch nicht angesehenen Werbeunterbrechungen generieren.

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 Übertragung über das Streaming- und Befehlszeilentool, indem Sie auf das Cast-Symbol klicken. Die VMAP-Anzeigen sollten abgespielt werden, gefolgt vom Hauptinhalt.

7. VAST zu Ihrem Content hinzufügen

Wie bereits erwähnt, werden viele Anzeigentypen im Web Receiver SDK unterstützt. In diesem Abschnitt werden die APIs beschrieben, die für die Integration 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.

Kopieren Sie nach dem Interceptor der Ladeanfrage Folgendes in die Datei js/receiver.js. Es enthält sechs VAST-Unterbrechungsclips aus DoubleClick und einen zufälligen correlator-Wert. Diese Pausenclips sind fünf Unterbrechungen zugewiesen. Die position jeder Pause wird auf eine Zeit in Sekunden relativ zum Hauptcontent festgelegt, einschließlich der Pausen von Pre-Roll (position auf 0) und Post-Roll (position auf -1).

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: Die Eigenschaft breakClipIds einer Unterbrechung ist ein Array. Jeder Unterbrechung können also mehrere Pausenclips zugewiesen werden.

Suchen Sie in Ihrem js/receiver.js file nach dem Abfangen von LOAD-Nachrichten und ersetzen Sie ihn durch den folgenden Code. Die VMAP-Arbeit ist auskommentiert, um Anzeigen vom Typ VAST zu präsentieren.

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 eine Übertragung über das Streaming- und Befehlszeilentool, indem Sie auf das Cast-Symbol klicken. Die VAST-Anzeigen sollten abgespielt werden, gefolgt vom Hauptcontent.

8. Werbeunterbrechung überspringen

CAF hat eine Klasse namens BreakManager, die Sie bei der Implementierung benutzerdefinierter Geschäftsregeln für die Funktionsweise von Anzeigen unterstützt. Eine dieser Funktionen ermöglicht Apps, Pausen programmatisch zu überspringen und Clips je nach bestimmten Bedingungen zu zerstören. In diesem Beispiel wird gezeigt, wie eine Werbeunterbrechung übersprungen wird, deren Position sich innerhalb der ersten 30 Sekunden des Contents befindet, aber nicht innerhalb der Post-Roll-Anzeigen. Wenn Sie die im vorherigen Abschnitt konfigurierten VAST-Anzeigen verwenden, sind fünf Unterbrechungen definiert: eine Pre-Roll-, 3 Mid-Roll-Werbeunterbrechungen (15, 60 und 100 Sekunden) und eine Post-Roll-Pause. Wenn alle Schritte abgeschlossen sind, werden nur die Pre-Roll- und Mid-Roll-Anzeigen übersprungen, deren Position 15 Sekunden liegt.

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

const breakManager = playerManager.getBreakManager();

Die App sollte einen Interceptor mit einer Regel einrichten, die Werbeunterbrechungen ignoriert, die vor 30 Sekunden stattfinden, und dabei alle Post-Roll-Werbeunterbrechungen im Auge behalten, da ihre position-Werte -1 sind. Dieser Interceptor funktioniert wie der LOAD-Interceptor auf PlayerManager, mit dem Unterschied, dass dieser spezifisch für das Laden von Pausen-Clips ist. Legen Sie ihn nach dem Interceptor der LOAD-Anfrage und vor der Funktionsdeklaration addVASTBreaksToMedia 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 null zurückgeben, wird die Verarbeitung von BreakClip übersprungen. Wenn für eine Break keine Pausenclips definiert sind, wird die Unterbrechung selbst übersprungen.

Speichern Sie die Änderungen in js/receiver.js und laden Sie die Datei auf Ihren Webserver hoch. Starten Sie eine Übertragung über das Streaming- und Befehlszeilentool, indem Sie auf das Cast-Symbol klicken. Die VAST-Anzeigen sollten verarbeitet werden. Pre-Roll-Anzeigen und erste Mid-Roll-Anzeigen, deren position 15 Sekunden lang ist, werden nicht wiedergegeben.

9. Suchverhalten für Werbeunterbrechung anpassen

Beim Durchsuchen vergangener Pausen werden bei der Standardimplementierung alle Break-Elemente abgerufen, deren Position zwischen den seekFrom- und seekTo-Werten des Suchvorgangs liegt. Aus dieser Liste von Unterbrechungen gibt das SDK die Break wieder, deren position dem Wert seekTo am nächsten ist und deren Attribut isWatched auf false festgelegt ist. Die isWatched-Eigenschaft dieser Pause wird dann auf true gesetzt und der Player beginnt mit der Wiedergabe der Pausenclips. Nach der Wiedergabe der Pause wird die Wiedergabe des Hauptinhalts an der Position seekTo fortgesetzt. Wenn keine solche Unterbrechung vorhanden ist, wird keine Pause wiedergegeben und der Hauptinhalt wird an der Position seekTo fortgesetzt.

Mit der setBreakSeekInterceptor API in BreakManager kannst du festlegen, welche Pausen bei der Suche abgespielt werden. Wenn eine Anwendung ihre benutzerdefinierte Logik über diese API bereitstellt, wird sie vom SDK immer dann aufgerufen, wenn ein Suchvorgang über eine oder mehrere Unterbrechungen hinweg ausgeführt wird. Der Callback-Funktion wird ein Objekt übergeben, das alle Pausen zwischen der Position seekFrom und seekTo enthält. Die Anwendung muss dann BreakSeekData ändern und zurückgeben.

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

Kopieren Sie Folgendes in die Datei js/receiver.js unter der Definition in 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 abgespielt.

Speichern Sie die Änderungen in js/receiver.js und laden Sie die Datei auf Ihren Webserver hoch. Starten Sie eine Übertragung über das Streaming- und Befehlszeilentool, indem Sie auf das Cast-Symbol klicken. Die VAST-Anzeigen sollten verarbeitet werden. Pre-Roll-Anzeigen und erste Mid-Roll-Anzeigen, deren position 15 Sekunden lang ist, werden nicht wiedergegeben.

Warten Sie, bis die Wiedergabezeit 30 Sekunden erreicht hat, um alle Unterbrechungen zu überspringen, die beim Abfangen des Ladens von Pausenclips übersprungen wurden. Wenn Sie diese erreicht haben, senden Sie einen Suchbefehl über den Tab Mediensteuerung. Geben Sie im Eingabefeld Seek Into Media (In Medien suchen) 300 Sekunden ein und klicken Sie auf die Schaltfläche TO. Beachten Sie die Logs, die im Break Seek Interceptor ausgegeben werden. Das Standardverhalten sollte jetzt überschrieben werden, um die Pause näher an der seekFrom-Zeit wiederzugeben.

10. Glückwunsch

Jetzt wissen Sie, wie Sie mit dem neuesten Cast Receiver SDK Werbung zu Ihrer Empfänger-App hinzufügen.

Weitere Informationen findest du im Entwicklerhandbuch zu Werbeunterbrechungen.