Cast SDK in die Web Sender App einbinden

In diesem Entwicklerleitfaden wird beschrieben, wie du deiner Web Sender App mithilfe des Cast SDK die Google Cast-Unterstützung hinzufügst.

Terminologie

Das Mobilgerät oder der Browser ist der Sender, der die Wiedergabe steuert. Das Google Cast-Gerät ist der Empfänger, der den Inhalt auf dem Bildschirm für die Wiedergabe 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 an die einfachere übergeordnete Framework API aus, 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 bilden. Die Absender-App oder die 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 ist eine HTML/JavaScript-App, die auf Chromecast oder einem Google Cast-Gerät ausgeführt wird.

Das Absender-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 deine App die Funktionen von Google Cast implementieren kann, muss sie den Speicherort des Google Cast Web Sender SDK kennen (siehe unten). Fügen Sie den URL-Abfrageparameter loadCastFramework hinzu, um auch die Web Sender Framework API zu laden. Alle Seiten Ihrer App müssen wie folgt 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 den folgenden Hauptkomponenten:

  • Das CastContext ist ein Singleton-Objekt, das Informationen zum aktuellen Umwandlungsstatus liefert und Ereignisse für Änderungen des Umwandlungsstatus und des Status der Umwandlungssitzung auslöst.
  • Das CastSession-Objekt verwaltet die Sitzung. Es stellt Statusinformationen bereit und löst Ereignisse wie Änderungen der Gerätelautstärke, der Stummschaltung und der App-Metadaten aus.
  • Das Cast-Symbol ist ein einfaches benutzerdefiniertes HTML-Element, mit dem die HTML-Schaltfläche erweitert wird. Wenn das bereitgestellte Cast-Symbol nicht ausreicht, kannst du ein Cast-Symbol mithilfe des Cast-Status implementieren.
  • 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

Die Komponente für das Cast-Symbol in Ihrer App wird vollständig vom Framework verwaltet. Dies umfasst die Verwaltung der Sichtbarkeit sowie die Verarbeitung von Klickereignissen.

<google-cast-launcher></google-cast-launcher>

Alternativ können Sie die Schaltfläche programmatisch erstellen:

document.createElement("google-cast-launcher");

Sie können bei Bedarf weitere Stile auf das Element anwenden, z. B. Größe oder Positionierung. Wählen Sie mit dem Attribut --connected-color die Farbe für den Status des verbundenen Web Receivers und --disconnected-color für den Status „Getrennt“ aus.

Initialisierung

Nach dem Laden der Framework API ruft die App den Handler window.__onGCastApiAvailable auf. Sorgen Sie dafür, dass die Anwendung diesen Handler auf window festlegt, bevor die Absenderbibliothek geladen wird.

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 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) mithilfe eines CastOptions-Objekts verwendet, um den 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();

Mit CastSession können Medien mithilfe von loadMedia(loadRequest) auf das verbundene Übertragungsgerät geladen werden. Erstellen Sie zuerst ein MediaInfo mit contentId und contentType sowie allen anderen Informationen im Zusammenhang mit dem Inhalt. Erstellen Sie dann daraus eine LoadRequest und legen Sie alle relevanten Informationen für die Anfrage fest. Rufen Sie schließlich 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 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.

Du kannst in RemotePlayer auf Player-Statusvariablen zugreifen. Alle Interaktionen mit dem RemotePlayer, einschließlich Callbacks für Medienereignisse und Befehle, werden mit RemotePlayerController verarbeitet.

var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);

Über das RemotePlayerController kann die App die gesamte Mediensteuerung für die geladenen Medien über WIEDERGEBEN, PAUSE, STOP und SEEK ausführen.

  • WIEDERGEBEN/PAUSE: playerController.playOrPause();
  • BEENDEN: playerController.stop();
  • ANZEIGEN: playerController.seek();

RemotePlayer und RemotePlayerController können mit Datenbindungs-Frameworks wie Polymer oder Angular verwendet werden, um einen Remote-Player 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

Während der Medienwiedergabe treten verschiedene Ereignisse auf, die erfasst werden können, indem Listener für verschiedene cast.framework.RemotePlayerEventType-Ereignisse im RemotePlayerController-Objekt festgelegt werden.

Verwenden Sie zum Abrufen der Informationen zum Medienstatus das Ereignis cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED, das ausgelöst wird, wenn sich die Wiedergabe ändert und wenn CastSession.getMediaSession().media geändert wird.

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 „Pause“, „Wiedergabe“, „Fortsetzen“ oder „Spulen“ 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.

Funktionsweise der Sitzungsverwaltung

Mit dem Cast SDK wird das Konzept einer Cast-Sitzung eingeführt. Dabei werden alle Schritte kombiniert, um eine Verbindung zu einem Gerät herzustellen, eine Web-Receiver-App zu starten (oder der App beizutreten), eine Verbindung zu dieser App herzustellen und einen Mediensteuerungskanal zu initialisieren. Weitere Informationen zu Streamingsitzungen und zum Web Receiver-Lebenszyklus findest du im Leitfaden zum Lebenszyklus von Anwendungen für 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 steht beispielsweise für Sitzungen mit Übertragungsgeräten. Deine App kann über CastContext.getCurrentSession() auf die aktuell aktive Übertragungssitzung zugreifen.

Fügen Sie zum Überwachen des Sitzungsstatus dem CastContext einen Listener für den Ereignistyp CastContextEventType.SESSION_STATE_CHANGED hinzu.

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 Streaming-Dialogfeld auf die Schaltfläche „Streaming beenden“ klickt, kannst du in deinem Listener einen Listener für den Ereignistyp RemotePlayerEventType.IS_CONNECTED_CHANGED hinzufügen. Prüfen Sie im Listener, ob RemotePlayer nicht verbunden 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 Streamen zwar direkt über die Cast-Schaltfläche des Frameworks steuern, der Sender selbst kann das Streamen aber über das aktuelle 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. Nutzer können vorhandene Audio- und Videostreams mithilfe von Sprachbefehlen, der Google Home App oder Smart Displays auf andere Geräte verschieben. Die Medienwiedergabe wird auf einem Gerät (Quelle) und auf einem anderen Gerät (dem Ziel) beendet. Jedes Übertragungsgerät mit der neuesten Firmware kann als Quellen oder Ziele in einer Streamübertragung dienen.

Wenn Sie das neue Zielgerät während der Streamübertragung abrufen möchten, rufen Sie CastSession#getCastDevice() auf, wenn das Ereignis cast.framework.SessionState.SESSION_RESUMED aufgerufen wird.

Weitere Informationen finden Sie unter Stream-Übertragung mit Web Receiver.

Zurück
Einrichtung
Weiter
Erweiterte Funktionen hinzufügen