Zintegruj SDK Cast z aplikacją Web Sender

Ten przewodnik dla programistów opisuje, jak dodać obsługę Google Cast do aplikacji internetowej nadawcy za pomocą pakietu Cast SDK.

Terminologia

Urządzenie mobilne lub przeglądarka to nadawca, który steruje odtwarzaniem. Urządzenie Google Cast to odbiorca, który wyświetla treści na ekranie.

Pakiet SDK Web Sender składa się z 2 części: interfejsu Framework API (cast.framework) i interfejsu Base API (chrome.cast). Zasadniczo wywołania są wykonywane w prostszym interfejsie Framework API wyższego poziomu, a następnie przetwarzane przez interfejs Base API niższego poziomu.

Sender framework odnosi się do interfejsu API, modułu i powiązanych zasobów, które stanowią otoczkę dla funkcji niższego poziomu. Aplikacja nadawcy lub aplikacja Google Cast na Chrome to aplikacja internetowa (HTML/JavaScript) działająca w przeglądarce Chrome na urządzeniu nadawcy. Aplikacja odbiornika internetowego to aplikacja HTML/JavaScript działająca na urządzeniu Chromecast lub Google Cast.

Platforma nadawcy używa asynchronicznego wywołania zwrotnego, aby informować aplikację nadawcy o zdarzeniach i przechodzić między różnymi stanami cyklu życia aplikacji Cast.

Wczytywanie biblioteki

Aby aplikacja mogła korzystać z funkcji Google Cast, musi znać lokalizację pakietu SDK Google Cast Web Sender, jak pokazano poniżej. Dodaj parametr zapytania adresu URL loadCastFramework, aby wczytać też interfejs Web Sender Framework API. Wszystkie strony aplikacji muszą odwoływać się do biblioteki w następujący sposób:

<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

Platforma

Pakiet SDK Web Sender używa przestrzeni nazw cast.framework.*. Przestrzeń nazw reprezentuje:

  • metody lub funkcje, które wywołują operacje w interfejsie API;
  • Detektory zdarzeń dla funkcji detektora w interfejsie API

Platforma składa się z tych głównych komponentów:

  • CastContext to obiekt singleton, który dostarcza informacji o bieżącym stanie Cast i wywołuje zdarzenia dotyczące zmian stanu Cast i sesji Cast.
  • Obiekt CastSession zarządza sesją – dostarcza informacje o stanie i wywołuje zdarzenia, takie jak zmiany głośności urządzenia, stanu wyciszenia i metadanych aplikacji.
  • Element przycisku Cast, który jest prostym niestandardowym elementem HTML rozszerzającym przycisk HTML. Jeśli udostępniony przycisk Cast nie wystarczy, możesz użyć stanu Cast, aby zaimplementować przycisk Cast.
  • RemotePlayerController zapewnia wiązanie danych, które upraszcza implementację odtwarzacza zdalnego.

Pełny opis przestrzeni nazw znajdziesz w dokumentacji interfejsu Google Cast Web Sender API.

Przycisk Cast

Komponent przycisku Cast w aplikacji jest w pełni obsługiwany przez platformę. Obejmuje to zarządzanie widocznością oraz obsługę zdarzeń kliknięcia.

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

Możesz też utworzyć przycisk automatycznie:

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

W razie potrzeby możesz zastosować do elementu dodatkowe style, takie jak rozmiar czy położenie. Użyj atrybutu --connected-color, aby wybrać kolor stanu połączonego odbiornika internetowego, i --disconnected-color, aby wybrać kolor stanu rozłączonego.

Zdarzenie inicjujące

Po wczytaniu interfejsu API platformy aplikacja wywoła moduł obsługi window.__onGCastApiAvailable. Upewnij się, że aplikacja ustawia ten moduł obsługi w window przed wczytaniem biblioteki nadawcy.

W tym module obsługi inicjujesz interakcję Cast, wywołując metodę setOptions(options) klasy CastContext.

Na przykład:

<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
  if (isAvailable) {
    initializeCastApi();
  }
};
</script>

Następnie zainicjuj interfejs API w ten sposób:

initializeCastApi = function() {
  cast.framework.CastContext.getInstance().setOptions({
    receiverApplicationId: applicationId,
    autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED
  });
};

Najpierw aplikacja pobiera instancję singletonu obiektu CastContext dostarczonego przez platformę. Następnie używa setOptions(options) z obiektem CastOptions, aby ustawić applicationID.

Jeśli używasz domyślnego odbiornika multimediów, który nie wymaga rejestracji, zamiast applicationID używasz stałej wstępnie zdefiniowanej przez pakiet SDK Web Sender, jak pokazano poniżej:

cast.framework.CastContext.getInstance().setOptions({
  receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});

Sterowanie multimediami

Po zainicjowaniu CastContext aplikacja może w każdej chwili pobrać bieżący CastSession za pomocą getCurrentSession().

var castSession = cast.framework.CastContext.getInstance().getCurrentSession();

CastSession może służyć do wczytywania multimediów na połączone urządzenie Cast za pomocą loadMedia(loadRequest). Najpierw utwórz MediaInfo, używając contentId i contentType oraz innych informacji związanych z treścią. Następnie utwórz z niego obiekt LoadRequest, ustawiając wszystkie odpowiednie informacje dotyczące żądania. Na koniec wywołaj funkcję loadMedia(loadRequest) w obiekcie CastSession.

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); });

Metoda loadMedia zwróci obiekt Promise, którego można użyć do wykonania wszelkich niezbędnych operacji, aby uzyskać pomyślny wynik. Jeśli obietnica zostanie odrzucona, argumentem funkcji będzie chrome.cast.ErrorCode.

Dostęp do zmiennych stanu odtwarzacza możesz uzyskać w RemotePlayer. Wszystkie interakcje z obiektem RemotePlayer, w tym wywołania zwrotne i polecenia zdarzeń multimedialnych, są obsługiwane przez obiekt RemotePlayerController.

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

RemotePlayerController zapewnia aplikacji pełne opcje sterowania multimediami, w tym nad funkcjami ODTWARZANIA, WSTRZYMYWANIA, ZATRZYMYWANIA i PRZEWIJANIA załadowanych multimediów.

  • ODTWARZANIE/WSTRZYMANIE: playerController.playOrPause();
  • STOP: playerController.stop();
  • SEEK: playerController.seek();

Elementy RemotePlayer i RemotePlayerController mogą być używane z platformami wiązania danych, takimi jak Polymer czy Angular, do implementacji odtwarzacza zdalnego.

Oto fragment kodu dla Angulara:

<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>

Stan multimediów

Podczas odtwarzania multimediów występują różne zdarzenia, które można przechwytywać, ustawiając detektory różnych zdarzeń cast.framework.RemotePlayerEventType w obiekcie RemotePlayerController.

Aby uzyskać informacje o stanie multimediów, użyj zdarzenia cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED, które jest wywoływane, gdy zmienia się odtwarzanie i gdy zmienia się CastSession.getMediaSession().media.

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;
  });

Gdy wystąpią zdarzenia takie jak wstrzymanie, odtworzenie, wznowienie lub wyszukiwanie, aplikacja musi na nie zareagować i zsynchronizować się z aplikacją odbiornika internetowego na urządzeniu Cast. Więcej informacji znajdziesz w sekcji Aktualizacje stanu.

Jak działa zarządzanie sesjami

Pakiet Cast SDK wprowadza koncepcję sesji przesyłania, której ustanowienie łączy kroki łączenia się z urządzeniem, uruchamiania aplikacji Web Receiver (lub dołączania do niej), łączenia się z tą aplikacją i inicjowania kanału sterowania multimediami. Więcej informacji o sesjach Cast i cyklu życia odbiornika internetowego znajdziesz w przewodniku po cyklu życia aplikacji na odbiorniku internetowym.

Sesjami zarządza klasa CastContext, którą aplikacja może pobrać za pomocą cast.framework.CastContext.getInstance(). Poszczególne sesje są reprezentowane przez podklasy klasy Session. Na przykład CastSession reprezentuje sesje na urządzeniach przesyłających. Aplikacja może uzyskać dostęp do aktualnie aktywnej sesji przesyłania za pomocą CastContext.getCurrentSession().

Aby monitorować stan sesji, dodaj detektor do CastContext dla typu zdarzenia CastContextEventType.SESSION_STATE_CHANGED.

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;
    }
  })

W przypadku rozłączenia, np. gdy użytkownik kliknie przycisk „Zatrzymaj przesyłanie” w oknie Cast, możesz dodać detektor typu zdarzenia RemotePlayerEventType.IS_CONNECTED_CHANGED. W detektorze sprawdź, czy RemotePlayer jest odłączony. Jeśli tak, zaktualizuj stan lokalnego odtwarzacza. Na przykład:

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.IS_CONNECTED_CHANGED, function() {
    if (!player.isConnected) {
      console.log('RemotePlayerController: Player disconnected');
      // Update local player to disconnected state
    }
  });

Użytkownik może bezpośrednio kontrolować zakończenie przesyłania za pomocą przycisku Cast, ale nadawca może zatrzymać przesyłanie za pomocą bieżącego obiektu CastSession.

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);
}

Przeniesienie odtwarzania

Zachowanie stanu sesji jest podstawą przenoszenia odtwarzania, dzięki któremu użytkownicy mogą przenosić istniejące strumienie audio i wideo między urządzeniami za pomocą poleceń głosowych, aplikacji Google Home lub inteligentnych ekranów. Odtwarzanie multimediów zostanie zatrzymane na jednym urządzeniu (źródłowym) i będzie kontynuowane na innym (docelowym). Każde urządzenie Cast z najnowszym oprogramowaniem układowym może służyć jako źródło lub miejsce docelowe przeniesienia odtwarzania.

Aby uzyskać nowe urządzenie docelowe podczas przenoszenia odtwarzania, wywołaj CastSession#getCastDevice(), gdy wywoływane jest zdarzenie cast.framework.SessionState.SESSION_RESUMED.

Więcej informacji znajdziesz w artykule Przenoszenie odtwarzania w odbiorniku internetowym.

Wstecz
Konfiguracja
Dalej
Dodaj funkcje zaawansowane