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 durchCastReceiverContext
ersetzt. Dies ist ein Singleton, das die Streamingsitzung, Absender, benutzerdefinierte Nachrichten und globale Systemereignisse verwaltet. MitCastReceiverOptions
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 PropertyPlayerManager
ersetzt, die ein Attribut desCastReceiverContext
-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 vonPlaybackConfig
bereitgestellt. Diese kann global oder pro Ladeanfrage bereitgestellt werden.
Mit PlayerManager
werden auch die neuen untergeordneten Verwaltungskonten verfügbar:
TextTracksManager
: Medientext-Tracks verwaltenAudioTracksManager
: Audiotracks verwaltenQueueManager
: die Warteschlange verwaltenBreakManager
: Anzeigen verwalten
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.