In diesem Entwicklerhandbuch wird erläutert, wie Sie mit dem Cast SDK Google Cast-Unterstützung zu Ihrer Websender-App hinzufügen.
Terminologie
Das Mobilgerät oder der Browser ist der Sender, über den die Wiedergabe gesteuert wird. Das Google Cast-Gerät ist der Empfänger, der den Inhalt auf dem Bildschirm anzeigt.
Das Web Sender SDK besteht aus zwei Teilen: der Framework API (cast.framework) und der Base API (chrome.cast). Im Allgemeinen führen Sie Aufrufe über die einfachere, übergeordnete Framework API aus, die dann von der untergeordneten API verarbeitet wird.
Das Absender-Framework bezieht sich auf die Framework API, das Modul und die zugehörigen Ressourcen, die einen Wrapper für untergeordnete Funktionen bereitstellen. Die Absender-App oder Google Cast-Chrome-App bezieht sich auf eine Web-App (HTML/JavaScript), die in einem Chrome-Browser auf einem Absendergerät ausgeführt wird. Eine Web Receiver App bezieht sich auf eine HTML/JavaScript-App, die auf Chromecast oder einem Google Cast-Gerät ausgeführt wird.
Das Sender-Framework verwendet ein asynchrones Callback-Design, um die Sender-App über Ereignisse zu informieren und zwischen verschiedenen Zuständen des Lebenszyklus der Cast-App zu wechseln.
Bibliothek laden
Damit die Funktionen von Google Cast in Ihrer App implementiert werden können, muss der Standort des Google Cast Web Sender SDK bekannt sein, wie unten dargestellt. Fügen Sie den URL-Abfrageparameter loadCastFramework hinzu, um die Web Sender Framework API ebenfalls zu laden. Alle Seiten Ihrer App müssen folgendermaßen auf die Bibliothek verweisen:
<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
Framework
Das Web Sender SDK verwendet den Namespace cast.framework.*. Der Namespace stellt Folgendes dar:
- Methoden oder Funktionen, die Vorgänge in der API aufrufen
- Event-Listener für Listener-Funktionen in der API
Das Framework besteht aus diesen Hauptkomponenten:
- Die
CastContext
ist ein Singleton-Objekt, das Informationen zum aktuellen Cast-Status liefert und die Ereignisse für den Status des Cast-Status und des Cast-Sitzungen auslöst. - Mit dem Objekt
CastSession
wird die Sitzung verwaltet. Es liefert Statusinformationen und löst Ereignisse aus, z. B. Änderungen des Gerätelautstärke, des Stummschaltungsstatus und der App-Metadaten. - Das Cast-Schaltflächenelement ist ein einfaches benutzerdefiniertes HTML-Element, das die HTML-Schaltfläche erweitert. Wenn das bereitgestellte Cast-Symbol nicht ausreicht, kannst du mit dem Cast-Status ein Cast-Symbol implementieren.
RemotePlayerController
bietet die Datenbindung, um die Implementierung des Remote-Players zu vereinfachen.
Eine vollständige Beschreibung des Namespace finden Sie in der Referenz zur Google Cast Web Sender API.
Cast-Symbol
Die Komponente für das Cast-Symbol in Ihrer App wird vollständig vom Framework verwaltet. Dazu gehören die Sichtbarkeitsverwaltung und die Verarbeitung von Klickereignis-Ereignissen.
<google-cast-launcher></google-cast-launcher>
Alternativ können Sie die Schaltfläche programmatisch erstellen:
document.createElement("google-cast-launcher");
Bei Bedarf können Sie einen weiteren Stil wie Größe oder Positionierung auf das Element anwenden. Wähle mit dem Attribut --connected-color
die Farbe für den Status „verbundener Webempfänger“ und --disconnected-color
für die Verbindung aus.
Initialisierung
Nach dem Laden der Framework API ruft die App den Handler window.__onGCastApiAvailable
auf. Achten Sie darauf, dass die Anwendung diesen Handler für window
festlegt, bevor Sie die Absenderbibliothek laden.
In diesem Handler initialisieren Sie die Cast-Interaktion. Rufen Sie dazu die Methode setOptions(options)
von CastContext
auf.
Beispiel:
<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
if (isAvailable) {
initializeCastApi();
}
};
</script>
Anschließend initialisieren Sie die API so:
initializeCastApi = function() {
cast.framework.CastContext.getInstance().setOptions({
receiverApplicationId: applicationId,
autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED
});
};
Zuerst ruft die App die Singleton-Instanz des vom Framework bereitgestellten CastContext
-Objekts ab. Anschließend wird setOptions(options)
mit einem CastOptions
-Objekt verwendet, um applicationID
festzulegen.
Wenn Sie den Standard-Medienempfänger verwenden, für den keine Registrierung erforderlich ist, verwenden Sie anstelle des applicationID
eine Konstante, die vom Web Sender SDK wie unten dargestellt konfiguriert wird:
cast.framework.CastContext.getInstance().setOptions({
receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});
Mediensteuerung
Sobald CastContext
initialisiert wurde, kann die aktuelle CastSession
-Funktion jederzeit mit getCurrentSession()
abrufen.
var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
Mit CastSession
können Medien mithilfe von loadMedia(loadRequest)
auf das verbundene Cast-Gerät geladen werden.
Erstellen Sie zuerst einen MediaInfo
. Verwenden Sie dazu contentId
und contentType
sowie andere Informationen zum Inhalt. Erstellen Sie dann eine LoadRequest
und legen Sie alle relevanten Informationen für die Anfrage fest. Rufen Sie schließlich loadMedia(loadRequest)
auf Ihrer CastSession
auf.
var mediaInfo = new chrome.cast.media.MediaInfo(currentMediaURL, contentType);
var request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
function() { console.log('Load succeed'); },
function(errorCode) { console.log('Error code: ' + errorCode); });
Die Methode loadMedia
gibt ein Promise-Objekt zurück, mit dem alle erforderlichen Vorgänge für ein erfolgreiches Ergebnis ausgeführt werden können.
Wenn das Promise abgelehnt wird, ist das Funktionsargument ein chrome.cast.ErrorCode
.
Sie können in RemotePlayer
auf die Variablen für den Player-Status zugreifen.
Alle Interaktionen mit der RemotePlayer
, einschließlich Medienereignis-Callbacks und -Befehlen, werden mit RemotePlayerController
verarbeitet.
var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);
RemotePlayerController
gibt der App die vollständige Mediensteuerung von Play, PAUSE, STOP und SEEK für die geladenen Medien.
- SPIELEN/PAUSE:
playerController.playOrPause();
- STOPP:
playerController.stop();
- Springen:
playerController.seek();
RemotePlayer
und RemotePlayerController
können mit Datenbindungs-Frameworks wie Polymer oder Angular verwendet werden, um einen Remote-Player zu implementieren.
Hier sehen Sie ein Code-Snippet für Angular:
<button id="playPauseButton" class="playerButton" ng-disabled="!player.canPause" ng-click="controller.playOrPause()"> {{player.isPaused ? 'Play' : 'Pause'}} </button> <script> var player = new cast.framework.RemotePlayer(); var controller = new cast.framework.RemotePlayerController(player); // Listen to any player update, and trigger angular data binding update.controller.addEventListener( cast.framework.RemotePlayerEventType.ANY_CHANGE, function(event) { if (!$scope.$$phase) $scope.$apply(); }); </script>
Medienstatus
Während der Medienwiedergabe treten verschiedene Ereignisse auf, die erfasst werden können. Dazu werden Listener für verschiedene cast.framework.RemotePlayerEventType
-Ereignisse im RemotePlayerController
-Objekt eingerichtet.
Verwenden Sie das cast.framework.RemotePlayerEventType
.MEDIA_INFO_CHANGED
-Ereignis, um die Medienstatusinformationen abzurufen. Diese werden ausgelöst, wenn sich die Wiedergabe ändert und wenn sich die CastSession.getMediaSession().media
ändert.
playerController.addEventListener(
cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED, function() {
// Use the current session to get an up to date media status.
let session = cast.framework.CastContext.getInstance().getCurrentSession();
if (!session) {
return;
}
// Contains information about the playing media including currentTime.
let mediaStatus = session.getMediaSession();
if (!mediaStatus) {
return;
}
// mediaStatus also contains the mediaInfo containing metadata and other
// information about the in progress content.
let mediaInfo = mediaStatus.media;
});
Wenn Ereignisse wie das Pausieren, Wiedergeben, Fortsetzen oder Suchen stattfinden, muss die App darauf reagieren und eine Synchronisierung zwischen sich und der Web Receiver App auf dem Cast-Gerät ausführen. Weitere Informationen finden Sie unter Statusaktualisierungen.
Funktionsweise der Sitzungsverwaltung
Das Cast SDK stellt das Konzept einer Cast-Sitzung vor, bei der die Schritte zum Herstellen einer Verbindung zu einem Gerät, zum Starten (oder Beitreten) einer Web Receiver-App, zum Herstellen einer Verbindung zu dieser App und zum Initialisieren eines Mediensteuerungskanals definiert werden. Weitere Informationen zu Cast-Sitzungen und dem Lebenszyklus des Webempfängers finden Sie im Leitfaden zum Lebenszyklus von Anwendungen.
Sitzungen werden von der Klasse CastContext
verwaltet, die Ihre App über cast.framework.CastContext.getInstance()
abrufen kann.
Einzelne Sitzungen werden durch abgeleitete Klassen der Klasse Session
dargestellt. CastSession
steht beispielsweise für Sitzungen mit Übertragungsgeräten. Ihre App kann über CastContext.getCurrentSession()
auf die derzeit aktive Cast-Sitzung zugreifen.
Fügen Sie dem CastContext
für den Ereignistyp CastContextEventType
.SESSION_STATE_CHANGED
einen Listener hinzu, um den Sitzungsstatus zu überwachen.
var context = cast.framework.CastContext.getInstance();
context.addEventListener(
cast.framework.CastContextEventType.SESSION_STATE_CHANGED,
function(event) {
switch (event.sessionState) {
case cast.framework.SessionState.SESSION_STARTED:
case cast.framework.SessionState.SESSION_RESUMED:
break;
case cast.framework.SessionState.SESSION_ENDED:
console.log('CastContext: CastSession disconnected');
// Update locally as necessary
break;
}
})
Zum Trennen der Verbindung, z. B. wenn der Nutzer im Dialogfeld zum Streamen auf die Schaltfläche „Streaming beenden“ klickt, können Sie in Ihrem Listener einen Listener für den Ereignistyp RemotePlayerEventType
.IS_CONNECTED_CHANGED
hinzufügen. Prüfen Sie in Ihrem Listener, ob RemotePlayer
getrennt ist. Falls ja, aktualisiere den Status des lokalen Players nach Bedarf. Beispiel:
playerController.addEventListener(
cast.framework.RemotePlayerEventType.IS_CONNECTED_CHANGED, function() {
if (!player.isConnected) {
console.log('RemotePlayerController: Player disconnected');
// Update local player to disconnected state
}
});
Der Nutzer kann das Beenden von Cast direkt über das Cast-Symbol des Frameworks steuern. Der Sender kann aber das Streaming mit dem aktuellen CastSession
-Objekt beenden.
function stopCasting() {
var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
// End the session and pass 'true' to indicate
// that Web Receiver app should be stopped.
castSession.endSession(true);
}
Stream-Übertragung
Die Beibehaltung des Sitzungsstatus ist die Grundlage der Streamübertragung, bei der Nutzer vorhandene Audio- und Videostreams mithilfe von Sprachbefehlen, der Google Home App oder Smart Displays zwischen Geräten verschieben können. Die Medienwiedergabe wird auf einem Gerät (Quelle) beendet und auf einem anderen (Ziel) fortgesetzt. Jedes Übertragungsgerät mit der neuesten Firmware kann als Quellen oder Ziele in einer Streamübertragung verwendet werden.
Um das neue Zielgerät während der Stream-Übertragung abzurufen, rufen Sie beim Aufrufen des Ereignisses cast.framework.SessionState
.SESSION_RESUMED
CastSession#getCastDevice()
auf.
Weitere Informationen finden Sie unter Streamübertragung auf Webempfänger.