Zu Web Receiver migrieren

In diesem Leitfaden wird erläutert, wie Sie eine Cast Receiver v2-App zur neuesten Web Receiver App migrieren.

Das neue Cast Application Framework (CAF) SDK, auch bekannt als Web Receiver v3, ist ein wichtiges Upgrade gegenüber dem Receiver v2 SDK. Das Web Receiver SDK bietet ein einfaches, optimiertes SDK für die Entwicklung von Medien-Web Receiver-Anwendungen.

Der Web Receiver bietet eine API, die besser mit den neuen CAF-Sender-APIs übereinstimmt. Es bietet die vollständige Integration eines Players (MPL und Shaka) sowie vollständige Implementierung und Unterstützung für die Sprachbefehle für Cast Media und Google Assistant. Das CAF SDK bietet auch eine Standard-UI, die sich mithilfe von CSS einfach gestalten lässt, und einen Datenbindungsdienst, der die UI-Implementierung vereinfacht.

Warum migrieren?

Durch die Migration einer Receiver v2-Anwendung zu Web Receiver kann viel Code, der sich mit dem Player befasst, eliminiert werden, sodass Sie sich auf das Schreiben der anwendungsspezifischen Geschäftslogik konzentrieren können.

CAF bindet nahtlos MPL- und Shaka-Player ein, um eine breitere Palette von Inhaltstypen zu unterstützen, einschließlich HTTP-Live-Streaming (TS und CMAF), MPEG-DASH, Smooth Streaming und Typen, die von der Quell-Property Media Element (MP3, MP4, Icecast usw.) unterstützt werden. Eine vollständige Liste finden Sie unter Unterstützte Medien für Google Cast. Derzeit unterstützt CAF keinen vom Nutzer bereitgestellten Player.

Durch die Migration zu CAF wird die Sprachsteuerung für Google Assistant unterstützt. Jeder neue Google Assistant-Sprachbefehl wird bei der Verwendung von CAF automatisch unterstützt.

CAF unterstützt nicht nur neue Medienbefehle wie „Titel ändern nach Sprache“ und „Wiedergabegeschwindigkeit ändern“, sondern auch bessere Warteschlangen, integrierte Anzeigenunterstützung und besseren Live-Support.

Was hat sich geändert?

Die Web Receiver API versucht, den Konventionen zu folgen, die von CAF-Absendern für Android und iOS eingeführt wurden. Sie unterscheidet sich erheblich von v2.

Der Webempfänger verwendet für alle bereitgestellten APIs den neuen Namespace cast.framework anstelle des Namespace cast.receiver. Viele der Datenobjekte, die von v2 verwendet wurden, sind in CAF identisch und werden im Namespace cast.framework.messages angezeigt (hauptsächlich unter cast.receiver.media).

Die folgenden v2-Dienste werden durch entsprechende CAF-Dienste ersetzt:

  • Die Klasse CastReceiverManager wird durch CastReceiverContext ersetzt. Dies ist ein Singleton, das die Streamingsitzung, Absender, benutzerdefinierte Nachrichten und globale Systemereignisse verwaltet. Mit CastReceiverOptions kannst du globale Anwendungsoptionen (z. B. die Warteschlange, die Empfängerversion oder die Wiedergabekonfiguration) für den Kontext angeben.
  • Die Klasse MediaManager wird durch die Property PlayerManager ersetzt, die ein Attribut des CastReceiverContext-Singleton-Formats ist. Sie verwaltet die Mediensitzung, Medienanfragen, Google Assistant-Sprachanfragen (CommandAndControlManager in Version 2) und löst Medienereignisse aus. Die Konfiguration für die Spieler (cast.player.api.Host in MPL) wird von PlaybackConfig bereitgestellt. Diese kann global oder pro Ladeanfrage bereitgestellt werden.

Mit PlayerManager werden auch die neuen untergeordneten Verwaltungskonten verfügbar:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

// Set global options.
const options = new cast.framework.CastReceiverOptions();
options.versionCode = DEVELOPERS_APP_VERSION;

context.start(options);

Geschäftslogik des Empfängers

Empfänger-Handler von Version 2, die Empfänger sind (z. B. CastReceiverManager.onReady oder MediaManager.onLoad), um eine Geschäftslogik hinzuzufügen. In CAF werden die Event-Handler durch Ereignis-Listener (CastReceiverContext.addEventListener) und Nachrichtenabfangprogramme (PlayerManager.setMessageInterceptor) ersetzt. Der Webempfänger kann mehrere Ereignis-Listener für ein Ereignis (der Listener hat keinen Einfluss auf das Ereignis) und einen Interceptor pro Nachricht haben. Der Interceptor kann die Anfrage aktualisieren oder verarbeiten (eine geänderte Anfrage, eine Erfolgs- oder Fehlermeldung zurückgeben) und ein asynchroner Handler sein, der ein Versprechen zurückgibt.

Das Abfangen von Ladeanfragen ist der häufigste Ort, an dem eine anwendungsspezifische Logik hinzugefügt wird. Bei Ladeanfragen von einem Absender kann der Load Balancer die Content-ID in eine Inhalts-URL umwandeln. Das Abfangen von Anfragen wird auch für Vorab- und Precache-Anfragen aufgerufen, wenn kein expliziter Interceptor für das Vorabladen oder Precache bereitgestellt wurde.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      // Resolve entity to content id
      if (request.media.entity && !request.media.contentId) {
        return getMediaByEntity(request.media.entity).then(
            media => {
              request.media.contentId = media.url;
              return request;
            });
      }
      return request;
    });

Der benutzerdefinierte V2-Status-Handler wird auch für die Medienstatusnachricht durch einen Nachrichtenabfangen ersetzt. Web Receiver-Apps, die die Medien-URL nicht im Medienstatus verfügbar machen möchten, können einen URL-Resolver (PlayerManager.setMediaUrlResolver) bereitstellen, der die Medien-URL für eine Ladeanfrage bereitstellt. Diese URL wird intern von CAF verwendet und ist nicht im Medienstatus angegeben.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.MEDIA_STATUS,
    status => {
      // Disable seek.
      status.supportedMediaCommands &=
          ~cast.framework.messages.Command.SEEK
      return status;
    });

Events

Web Receiver bietet eine umfangreiche Reihe von Ereignissen von CastReceiverContext und PlayerManager. Web Receiver-Apps können mehrere Listener für jedes Ereignis haben und auch einen Listener für mehrere Ereignisse bereitstellen. Einige Gruppen von Ereignissen finden Sie unter cast.framework.events.category.

Die Ereignisse decken alle Nutzeranfragen, den Wiedergabefortschritt, die Playerverarbeitung und alle Ereignisse auf niedrigerer Ebene ab. Das Element wird nicht angezeigt.

Die Web Receiver App kann Ereignis-Listener hinzufügen, um Aktionen auszuführen (z. B. Definition der Texttracks, wenn der Ladevorgang abgeschlossen ist) oder für Analysen zu verwenden.

// Log all media commands
playerManager.addEventListener(
    cast.framework.events.category.REQUEST,
    event => logEvent(event.type));

Benutzerdefinierter Nachrichtenbus

CAF gibt den Nachrichtenbus in der API nicht frei. Stattdessen bietet er CastReceiverContext.addCustomMessageListener zum Hinzufügen eines Nachrichten-Listeners für einen bestimmten Namespace (nur einen pro Namespace) und CastReceiverContext.sendCustomMessage zum Senden einer Nachricht in einem Namespace. Alle Namespaces müssen vor dem Starten des Webempfängers (d. h. vor dem Aufruf von CastReceiverContext.start) deklariert werden. Die Namespaces können durch Hinzufügen eines Nachrichten-Listeners für sie deklariert werden oder können als Startoption in CastReceiverOptions.customNamespaces angegeben werden.

const options = new cast.framework.CastReceiverOptions();
options.customNamespaces = {
    CUSTOM_NS: cast.framework.system.MessageType.JSON
};
context.start(options);

context.sendCustomMessage(CUSTOM_NS, {
  type: 'status'
  message: 'Playing'
});

Standardbenutzeroberfläche

CAF bietet eine standardmäßige Web Receiver-UI, in der eine Fortschrittsanzeige für die Wiedergabe und nach Bedarf Medienmetadaten angezeigt werden. Die Standardbenutzeroberfläche wird als benutzerdefiniertes Element (<cast-media-player>) bereitgestellt, das mit CSS-ähnlichen Stilen gestaltet werden kann.

<style>
   cast-media-player { --splash-image: url("splash.png"); }
</style>
<cast-media-player></cast-media-player>

Zur weiteren Anpassung kann eine Web Receiver-App eine eigene Benutzeroberfläche implementieren. Der Web Receiver bietet die Klasse cast.framework.ui.PlayerDataBinder, um ein UI-Objekt an den Wiedergabestatus des Web Receivers zu binden.