Cast SDK in die Web Sender App einbinden

In diesem Entwicklerleitfaden wird beschrieben, wie du deiner Web Sender App mithilfe des 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). In der Regel führen Sie Aufrufe an die einfachere Framework API auf höherer Ebene 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 bereitstellen. Die Absender-App oder Google Cast Chrome-App bezieht sich auf eine Web-App (HTML/JavaScript), die in einem Chrome-Browser auf dem 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 Status des Lebenszyklus der Cast-App zu wechseln.

Bibliothek laden

Damit Ihre 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-Suchparameter 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 diesen Hauptkomponenten:

  • Das CastContext ist ein Singleton-Objekt, das Informationen zum aktuellen Übertragungsstatus bereitstellt und Ereignisse für Änderungen des Übertragungsstatus und der Übertragungssitzung auslöst.
  • Über das Objekt CastSession wird die Sitzung verwaltet. Es stellt Statusinformationen bereit und löst Ereignisse wie Änderungen der Gerätelautstärke, den Stummschaltungsstatus und die App-Metadaten aus.
  • Das Cast-Schaltflächenelement, ein einfaches benutzerdefiniertes HTML-Element, das die HTML-Schaltfläche erweitert. Wenn das bereitgestellte Cast-Symbol nicht ausreicht, können Sie es verwenden.
  • Der RemotePlayerController stellt die Datenbindung bereit, um die Implementierung des Remote-Players zu vereinfachen.

Eine vollständige Beschreibung des Namespace finden Sie in der Google Cast Web Sender API-Referenz.

Cast-Symbol

Die Cast-Schaltflächenkomponente 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 auch programmatisch erstellen:

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

Bei Bedarf lassen sich zusätzliche Stile wie 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 „Getrennt“.

Initialisierung

Nach dem Laden der Framework API ruft die App den Handler window.__onGCastApiAvailable auf. Achten Sie darauf, dass die Anwendung diesen Handler auf window festlegt, bevor Sie die Senderbibliothek laden.

In diesem Handler 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, der keine Registrierung erfordert, 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 das 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 über loadMedia(loadRequest) auf das verbundene Übertragungsgerät geladen werden. Erstelle zuerst ein MediaInfo. Verwende dazu contentId, contentType und alle anderen 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 Abschluss 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 für ein erfolgreiches Ergebnis erforderlichen Vorgänge ausgeführt werden können. Wenn das Promise abgelehnt wird, ist das Funktionsargument ein chrome.cast.ErrorCode.

Sie können auf Spielerstatusvariablen in RemotePlayer 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);

Über RemotePlayerController erhält die App die vollständige Mediensteuerung für die geladenen Medien.

  • WIEDERGABE/PAUSE: playerController.playOrPause();
  • STOPP: playerController.stop();
  • SUCHEN: 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 auf verschiedene cast.framework.RemotePlayerEventType-Ereignisse für das RemotePlayerController-Objekt festgelegt werden.

Zum Abrufen der Informationen zum Medienstatus verwenden Sie das Ereignis cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED. Dieses wird ausgelöst, wenn sich die Wiedergabe ändert, und wenn sich 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 Pause, Wiedergabe, Fortsetzung oder Suche auftreten, 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 Streamingsitzung ein. Dabei werden die Schritte zum Verbinden mit einem Gerät, Starten (oder Beitreten) einer Web Receiver-App, Verbindung zu dieser App und Initialisieren eines Mediensteuerungskanals kombiniert. Weitere Informationen zu Übertragungssitzungen und zum Lebenszyklus des Webempfängers finden Sie im Leitfaden zum Lebenszyklus von Anwendungen für Web Receiver.

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 repräsentiert beispielsweise Sitzungen mit Übertragungsgeräten. Deine App kann über CastContext.getCurrentSession() auf die derzeit aktive Streaming-Sitzung zugreifen.

Fügen Sie dem 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 Streaming-Dialogfeld auf die Schaltfläche „Streaming beenden“ klickt, können Sie einen Listener für den Ereignistyp RemotePlayerEventType.IS_CONNECTED_CHANGED in Ihrem Listener hinzufügen. Prüfen Sie im Listener, ob die Verbindung zu RemotePlayer getrennt ist. Falls ja, aktualisieren Sie 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 über die Cast-Schaltfläche des Frameworks direkt steuern. Der Sender selbst kann 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

Das Beibehalten 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 auf andere Geräte verschieben können. Die Wiedergabe von Medien 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 findest du unter Stream-Übertragung auf Web-Receiver.

Zurück
Einrichtung
Weiter
Erweiterte Funktionen hinzufügen