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

1. Übersicht

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 Mobilgeräten 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 so erweitern, dass sie einen Fernseher oder ein Soundsystem steuern kann. Mit dem Cast SDK können Sie die erforderlichen UI-Komponenten gemäß der Checkliste für das Google Cast-Design hinzufügen.

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

Ziele

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

Lerninhalte

• VMAP- und VAST-Unterbrechungen in Inhalte für Cast einbinden
• Clips überspringen
• So passen Sie das standardmäßige Werbeunterbrechungsverhalten bei der Suche an

Voraussetzungen

• Die aktuelle Version von Google Chrome.
• HTTPS-Hostingdienst wie Firebase Hosting oder ngrok
• Ein Google Cast-Gerät wie Chromecast oder Android TV mit Internetverbindung
• Einen Fernseher oder Monitor mit HDMI-Eingang oder Google Home Hub

Erfahrung

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

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

2. Beispielcode abrufen

Den gesamten Beispielcode auf Ihren Computer herunterladen...

file_downloadQuellcode herunterladen

und entpacken Sie die heruntergeladene ZIP-Datei.

3. Empfänger lokal bereitstellen

Damit Sie Ihren Web Receiver mit einem Übertragungsgerät verwenden können, muss es an einem Ort gehostet werden, an dem Ihr Cast-Gerät darauf zugreifen kann. Falls Sie bereits einen Server haben, der HTTPS unterstützt, überspringen Sie die folgende Anleitung und merken Sie sich die URL, da Sie sie im nächsten Abschnitt benötigen.

Wenn Sie keinen Server haben, können Sie Firebase Hosting oder ngrok verwenden.

Server ausführen

Sobald Sie den Dienst Ihrer Wahl eingerichtet haben, rufen Sie app-start auf und starten Sie Ihren Server.

Notieren Sie sich die URL des gehosteten Empfängers. Sie benötigen sie im nächsten Abschnitt.

4. App in der Cast Developer Console registrieren

Sie müssen Ihre Anwendung registrieren, um einen in diesem Codelab integrierten benutzerdefinierten Receiver 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.

Klicken Sie auf „Neue Anwendung hinzufügen“.

Wähle „Benutzerdefinierter Receiver“ aus. Das ist der Vorgang, den wir entwickeln.

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 Konsole generiert wird, nachdem Sie die Anwendung registriert haben. Die Absenderanwendung wird in einem späteren Abschnitt so konfiguriert, dass sie diese ID verwendet.

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

Klicke auf „Neues Gerä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 Ihre Seriennummer auch ermitteln, indem Sie Ihren Bildschirm in Chrome streamen, wenn Sie die Google Cast SDK-Entwicklerkonsole aufrufen.

Es dauert 5 bis 15 Minuten, bis der Empfänger und das Gerät zum Testen bereit sind. Warten Sie 5 bis 15 Minuten und starten Sie das Übertragungsgerät neu.

5. Das Startprojekt vorbereiten

Bevor Sie mit diesem Codelab beginnen, kann es hilfreich sein, den Entwicklerleitfaden für Google Ads zu lesen. Dort finden Sie eine Übersicht über die APIs für Werbeunterbrechungen.

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

• eine Absender-App auf einem Mobilgerät oder Laptop ausgeführt wird,
• Eine Receiver-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 app-start aus dem Download des Beispielcodes aus.
2. Öffnen Sie js/receiver.js und „index.html“.

Hinweis: Während Sie dieses Codelab durcharbeiten, sollte die von Ihnen ausgewählte Webhosting-Lösung mit den Änderungen aktualisiert werden. Achten Sie darauf, die Änderungen an die Hostwebsite zu übertragen, wenn Sie sie weiterhin validieren und testen.

App-Design

Wie bereits erwähnt, wird im Codelab eine Absender-App verwendet, um eine Cast-Sitzung zu starten, und eine Empfänger-App, die angepasst wird, um die APIs für Werbeunterbrechungen zu verwenden.

In diesem Codelab dient das Cast- und Befehlstool 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 Absender-App für den Test zu konfigurieren.

Hinweis: Wenn das Cast-Symbol nicht angezeigt wird, prüfen Sie, ob der Webempfänger und die Übertragungsgeräte ordnungsgemäß in der Cast-Entwicklerkonsole registriert sind. Schalten Sie alle Übertragungsgeräte aus, die Sie gerade registriert haben, falls Sie das noch nicht getan haben.

In diesem Codelab steht die Empfänger-App im Mittelpunkt. Sie 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 UI für die Receiver-App, die durch das cast-media-player-Element bereitgestellt wird. Außerdem werden das CAF SDK und die Cast Debug Protokollierung-Bibliotheken geladen.

receiver.js

Dieses Skript verwaltet die gesamte Logik für die Empfänger-App. Derzeit enthält es einen einfachen CAF-Empfänger, um den Cast-Kontext zu initialisieren und nach 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. Ihren Inhalten VMAP hinzufügen

Das Cast Web Receiver SDK unterstützt Anzeigen, die über Digital Video Multiple Ad Playlists, auch als VMAP bezeichnet, 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 die Eigenschaft vmapAdsRequest im Objekt MediaInformation bereit.

Erstellen Sie in der Datei js/receiver.js ein VastAdsRequest-Objekt. Suchen Sie die Funktion LOAD-Anfrage-Abfangfunktion 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 das Streaming über das Streaming- und Kommandotool, indem Sie auf das Cast-Symbol klicken. Die VMAP-Anzeigen sollten gefolgt vom Hauptinhalt abgespielt werden.

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 (auch als VAST bezeichnet) verfügbar sind. Wenn Sie den VMAP-Code aus dem vorherigen Abschnitt implementiert haben, kommentieren Sie ihn aus.

Kopiere den folgenden Code nach dem Abfangen der Ladeanfrage in deine js/receiver.js-Datei. Es enthält sechs VAST-Pausenclips von DoubleClick und einen zufälligen correlator-Wert. Diese Clips sind fünf Pausen zugewiesen. Für jede Werbeunterbrechung ist position auf einen Zeitpunkt in Sekunden relativ zum Hauptcontent festgelegt, einschließlich Pre-Roll- (position auf 0 festgelegt) und Post-Roll- (position auf -1 festgelegt) Pausen.

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. Das bedeutet, dass jeder Unterbrechung mehrere Clips zugewiesen werden können.

Suchen Sie in der Datei js/receiver.js file nach dem Abfangende von LOAD-Nachrichten und ersetzen Sie ihn durch den folgenden Code. Die VMAP-Elemente sind 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 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 Werbeunterbrechung

CAF hat eine Klasse namens BreakManager, die Sie bei der Implementierung benutzerdefinierter Geschäftsregeln für das Anzeigenverhalten unterstützt. Eine dieser Funktionen ermöglicht es Apps, Pausen programmatisch zu überspringen und Clips je nach Situation zu unterbrechen. 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. Nach Abschluss der Schritte werden nur die Pre-Roll und Mid-Rolls übersprungen, deren Position sich bei 15 Sekunden befindet.

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

const breakManager = playerManager.getBreakManager();

In der Anwendung sollte ein Interceptor mit einer Regel eingerichtet werden, um alle Werbeunterbrechungen zu ignorieren, die vor 30 Sekunden stattfinden, und dabei alle Post-Roll-Werbeunterbrechungen berücksichtigt werden, da ihr position-Wert -1 ist. Dieser Interceptor funktioniert wie der LOAD-Interceptor für PlayerManager, mit dem Unterschied, dass dieser speziell für das Laden von Pausenclips vorgesehen ist. Legen Sie diesen Wert nach dem LOAD-Anfrage-Abfangende und vor der Funktionsdeklaration addVASTBreaksToMedia fest.

Kopieren Sie den folgenden Code 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 Clips der Unterbrechung definiert sind, wird die Unterbrechung übersprungen.

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 verarbeitet werden. Beachte, dass die Pre-Roll und die erste Mid-Roll (mit position 15 Sekunden) nicht abgespielt werden.

9. Verhalten der Unterbrechungssuche anpassen

Beim Suchen vergangener Pausen ruft die Standardimplementierung alle Break-Elemente ab, deren Position zwischen den seekFrom- und seekTo-Werten 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. Das Attribut isWatched dieser Werbeunterbrechung wird dann auf true gesetzt und der Player beginnt mit der Wiedergabe der entsprechenden Clips. Nach der Pause wird die Wiedergabe mit dem Hauptinhalt ab 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 immer dann aufgerufen, wenn ein Suchvorgang über eine oder mehrere Unterbrechungen 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 BreakSeekData ändern und zurückgeben.

Zur Veranschaulichung der Nutzung wird im Beispiel unten das Standardverhalten überschrieben. Dabei werden alle Pausen, über die umgezogen wurden, und nur die erste in der Zeitachse wiedergegeben.

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 oder null zurückgibt, werden keine Unterbrechungen abgespielt.

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 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. Geben Sie dann einen Suchbefehl aus, indem Sie den Tab Media Control aufrufen. Geben Sie im Feld Seek Into Media (In Medien suchen) 300 Sekunden ein und klicken Sie auf die Schaltfläche TO (An). Beachten Sie die im Break Seek Interceptor ausgegebenen Protokolle. Das Standardverhalten sollte jetzt überschrieben werden, damit die Unterbrechung näher an der Zeit von seekFrom wiedergegeben wird.

10. Glückwunsch

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

Weitere Informationen findest du im Entwicklerleitfaden zu Werbeunterbrechungen.