In diesem Entwicklerhandbuch wird beschrieben, wie du deiner Web Sender App mit dem Cast SDK Google Cast-Unterstützung hinzufügst.
Terminologie
Das Mobilgerät oder der Browser ist der Absender, der die Wiedergabe steuert. Das Google Cast-Gerät ist der Empfänger, der den Inhalt zur Wiedergabe 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 werden Aufrufe an die einfachere Framework API auf höherer Ebene gesendet, die dann von der untergeordneten Base 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 Ihre App die Funktionen von Google Cast implementieren kann, muss sie den Standort des Google Cast Web Sender SDK kennen (siehe unten). Fügen Sie den URL-Suchparameter loadCastFramework hinzu, um auch die Web Sender Framework API zu laden. Alle Seiten Ihrer App müssen so 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 für die API aufrufen
- Ereignis-Listener für Listener-Funktionen in der API
Das Framework besteht aus folgenden Hauptkomponenten:
- Das
CastContext
ist ein Singleton-Objekt, das Informationen zum aktuellen Übertragungsstatus bereitstellt und Ereignisse für Statusänderungen des Übertragungsstatus und der Übertragungssitzung auslöst. - Das
CastSession
-Objekt verwaltet die Sitzung. Es stellt Statusinformationen bereit und löst Ereignisse wie Änderungen der Gerätelautstärke, des Stummschaltungsstatus und der App-Metadaten aus. - Das Element für die Cast-Schaltfläche ist ein einfaches benutzerdefiniertes HTML-Element, das die HTML-Schaltfläche erweitert. Wenn das bereitgestellte Cast-Symbol nicht ausreicht, können Sie es verwenden.
- Das
RemotePlayerController
stellt die Datenbindung bereit, 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
Das Cast-Symbol in Ihrer App wird vollständig vom Framework verwaltet. Dazu gehören die Verwaltung der Sichtbarkeit sowie die Verarbeitung von Klickereignissen.
<google-cast-launcher></google-cast-launcher>
Alternativ können Sie die Schaltfläche auch programmatisch erstellen:
document.createElement("google-cast-launcher");
Sie können bei Bedarf weitere Stile wie etwa Größe oder Positionierung auf das Element anwenden. Verwenden Sie das Attribut --connected-color
, um die Farbe für den Status des verbundenen Webempfängers auszuwählen, und --disconnected-color
für den Status der Verbindung.
Initialisierung
Nach dem Laden der Framework API ruft die Anwendung den Handler window.__onGCastApiAvailable
auf. Achten Sie darauf, dass die Anwendung diesen Handler auf window
festlegt, bevor Sie die Senderbibliothek laden.
Innerhalb dieses Handlers initialisieren Sie die Cast-Interaktion, indem Sie die Methode setOptions(options)
von CastContext
aufrufen.
Beispiel:
<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
if (isAvailable) {
initializeCastApi();
}
};
</script>
Anschließend initialisieren Sie die API wie folgt:
initializeCastApi = function() {
cast.framework.CastContext.getInstance().setOptions({
receiverApplicationId: applicationId,
autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED
});
};
Zuerst ruft die Anwendung die Singleton-Instanz des vom Framework bereitgestellten CastContext
-Objekts ab. Dann wird setOptions(options)
mit einem CastOptions
-Objekt verwendet, um applicationID
festzulegen.
Wenn Sie den Standardmedienempfänger verwenden, für den keine Registrierung erforderlich ist, verwenden Sie anstelle von applicationID
eine vom Web Sender SDK vordefinierte Konstante (siehe unten):
cast.framework.CastContext.getInstance().setOptions({
receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});
Mediensteuerung
Sobald CastContext
initialisiert wurde, kann die Anwendung den aktuellen CastSession
jederzeit mit getCurrentSession()
abrufen.
var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
CastSession
kann verwendet werden, um Medien mit loadMedia(loadRequest)
auf das verbundene Übertragungsgerät zu laden.
Erstellen Sie zuerst ein MediaInfo
. Verwenden Sie dazu contentId
und contentType
sowie andere Informationen, die sich auf den Inhalt beziehen. Erstellen Sie dann ein LoadRequest
daraus und legen Sie alle relevanten Informationen für die Anfrage fest. Rufen Sie zum Schluss loadMedia(loadRequest)
auf Ihrem 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 zurück, mit dem die erforderlichen Vorgänge für ein erfolgreiches Ergebnis ausgeführt werden können.
Wenn das Versprechen abgelehnt wird, ist das Funktionsargument ein chrome.cast.ErrorCode
.
Sie können in RemotePlayer
auf Spielerstatusvariablen zugreifen.
Alle Interaktionen mit 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 Kontrolle über die Medienwiedergabe, Pausieren, Stoppen und Suchen für die geladenen Medien.
- WIEDERGABE/PAUSE:
playerController.playOrPause();
- STOPPEN:
playerController.stop();
- SUCHEN:
playerController.seek();
RemotePlayer
und RemotePlayerController
können mit Datenbindungs-Frameworks wie Polymer oder Angular verwendet werden, um einen Remoteplayer zu implementieren.
Hier ist 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
Bei der Medienwiedergabe treten verschiedene Ereignisse auf, die erfasst werden können, indem Listener auf verschiedene cast.framework.RemotePlayerEventType
-Ereignisse für das RemotePlayerController
-Objekt festgelegt werden.
Die Informationen zum Medienstatus können Sie mit dem Ereignis cast.framework.RemotePlayerEventType
.MEDIA_INFO_CHANGED
abrufen. Dieses wird ausgelöst, wenn sich die Wiedergabe und CastSession.getMediaSession().media
ändern.
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;
});
Bei Ereignissen wie Pausieren, Abspielen, Fortsetzen oder Suchen muss die App darauf reagieren und zwischen sich selbst und der Web Receiver App auf dem Übertragungsgerät synchronisieren. Weitere Informationen finden Sie unter Statusaktualisierungen.
So funktioniert die Sitzungsverwaltung
Das Cast SDK führt das Konzept einer Cast-Sitzung ein. Dabei werden die Schritte zum Verbinden mit einem Gerät, Starten (oder Beitritt) einer Web-Receiver-App, Verbinden mit dieser App und Initialisieren eines Mediensteuerungskanals kombiniert. Weitere Informationen zu Übertragungssitzungen und dem Lebenszyklus des Webempfängers finden Sie in der Anleitung zum Lebenszyklus von Anwendungen für den Web Receiver.
Sitzungen werden von der Klasse CastContext
verwaltet, die Ihre Anwendung über cast.framework.CastContext.getInstance()
abrufen kann.
Einzelne Sitzungen werden durch abgeleitete Klassen der Klasse Session
dargestellt. CastSession
repräsentiert beispielsweise Sitzungen mit Übertragungsgeräten. Deine App kann über CastContext.getCurrentSession()
auf die derzeit aktive Streaming-Sitzung zugreifen.
Fügen Sie CastContext
einen Listener für den Ereignistyp CastContextEventType
.SESSION_STATE_CHANGED
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;
}
})
Wenn die Verbindung getrennt wird, z. B. wenn der Nutzer im Cast-Dialogfeld auf die Schaltfläche "Streaming beenden" klickt, können Sie dem Listener einen Listener für den Ereignistyp RemotePlayerEventType
.IS_CONNECTED_CHANGED
hinzufügen. Prüfen Sie im Listener, ob die Verbindung zu 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 Streaming direkt über die Cast-Schaltfläche des Frameworks steuern. Der Sender selbst kann das Streamen 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
Das Beibehalten des Sitzungsstatus ist die Grundlage der Streamübertragung, bei der Nutzer vorhandene Audio- und Videostreams über Sprachbefehle, die Google Home App oder Smart Displays zwischen Geräten verschieben können. Die Medienwiedergabe wird auf einem Gerät (der Quelle) beendet und auf einem anderen (dem Ziel) fortgesetzt. Jedes Übertragungsgerät mit der neuesten Firmware kann als Quellen oder Ziele bei einer Streamübertragung dienen.
Um das neue Zielgerät während der Streamübertragung zu erhalten, rufen Sie CastSession#getCastDevice()
auf, wenn das Ereignis cast.framework.SessionState
.SESSION_RESUMED
aufgerufen wird.
Weitere Informationen finden Sie unter Streamübertragung auf Web Receiver.