Zintegruj SDK Cast z aplikacją Web Sender

W tym przewodniku dla programistów opisujemy, jak dodać obsługę Google Cast do aplikacji WebSender za pomocą pakietu SDK Cast.

Terminologia

Urządzenie mobilne lub przeglądarka jest nadawcą, który kontroluje odtwarzanie, a urządzenie Google Cast to odbiornik, który wyświetla na ekranie treść, aby ją odtworzyć.

Pakiet SDK Web Sender składa się z 2 części: interfejsu Framework API (cast.framework) i interfejsu Base API (chrome.cast). Wywołania wykonuje się przy użyciu prostszego, wyższego poziomu interfejsu Framework Framework API, które są następnie przetwarzane przez interfejs Base API niższego poziomu.

Platforma nadawcy oznacza interfejs Framework API, moduł i powiązane zasoby, które zapewniają otokę funkcji niższego poziomu. Aplikacja nadawcy lub aplikacja Chrome Google Cast oznacza aplikację internetową (HTML/JavaScript) działającą w przeglądarce Chrome na urządzeniu nadawcy. Aplikacja internetowa odbiornika Web oznacza aplikację w języku HTML/JavaScript działającą na Chromecaście lub urządzeniu Google Cast.

Platforma nadawcy korzysta z asynchronicznego wywołania zwrotnego, który informuje aplikację nadawcy o zdarzeniach i przechodzi między różnymi stanami cyklu życia aplikacji Cast.

Wczytaj bibliotekę

Aby Twoja aplikacja mogła zaimplementować funkcje Google Cast, musi znać lokalizację pakietu SDK Google Cast Web Sender SDK, jak pokazano poniżej. Aby załadować także interfejs Web Sender Framework API, dodaj parametr zapytania URL loadCastFramework. Wszystkie strony aplikacji muszą się odwoływać do biblioteki w ten sposób:

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

Platforma

Pakiet SDK Web Sender korzysta z 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 pojedynczy obiekt, który dostarcza informacji o bieżącym stanie przesyłania i wyzwala zdarzenia związane ze zmianami stanu przesyłania i stanu sesji przesyłania.
  • Obiekt CastSession zarządza sesją – dostarcza informacje o stanie i aktywuje zdarzenia, takie jak zmiana głośności urządzenia, stanu wyciszenia czy metadane aplikacji.
  • Element przycisku Cast, czyli prosty niestandardowy element HTML, który rozszerza przycisk HTML. Jeśli podany przycisk Cast nie jest wystarczający, można go zaimplementować, używając stanu przesyłania.
  • Obiekt RemotePlayerController udostępnia 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 obsługiwany w całości 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 dowolne dodatkowe style, takie jak rozmiar lub położenie. Użyj atrybutu --connected-color, aby wybrać kolor stanu połączonego odbiornika internetowego i --disconnected-color, aby określić stan połączenia.

Zdarzenie inicjujące

Po wczytaniu interfejsu API platformy aplikacja wywoła moduł obsługi window.__onGCastApiAvailable. Przed załadowaniem biblioteki nadawcy upewnij się, że aplikacja ustawia ten moduł obsługi na platformie window.

W ramach tego modułu obsługi inicjujesz interakcję Cast, wywołując metodę setOptions(options) w komponencie 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 pojedynczą instancję obiektu CastContext udostępnionego przez platformę. Następnie przy użyciu obiektu CastOptions ustawia on applicationID za pomocą setOptions(options).

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 SDK, 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 podłączone urządzenie przesyłające za pomocą loadMedia(loadRequest). Najpierw utwórz MediaInfo, używając contentId i contentType, a także wszelkich innych informacji związanych z treścią. Następnie utwórz z niego LoadRequest, ustawiając wszystkie niezbędne informacje na potrzeby żądania. Na koniec zadzwoń do firmy loadMedia(loadRequest) na swoim urządzeniu 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 zwraca obietnicę, której można użyć do wykonania wszystkich operacji niezbędnych do uzyskania pomyślnego wyniku. Jeśli obietnica zostanie odrzucona, argumentem funkcji będzie chrome.cast.ErrorCode.

Zmienne stanu odtwarzacza znajdziesz tutaj: RemotePlayer. Wszystkie interakcje z obiektem RemotePlayer, w tym wywołania zwrotne i polecenia zdarzeń multimedialnych, są obsługiwane przez RemotePlayerController.

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

RemotePlayerController daje aplikacji pełną kontrolę nad multimediami: PLAY, PAUSE, STOP i SEEK dla wczytywanych multimediów.

  • ODTWARZANIE/WSTRZYMANIE: playerController.playOrPause();
  • ZATRZYMAJ: playerController.stop();
  • SZUKAJ: playerController.seek();

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

Oto fragment kodu do 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>

Stan multimediów

Podczas odtwarzania multimediów występują różne zdarzenia, które można przechwytywać przez ustawienie odbiorników dla 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 uruchamia się, gdy zmienia się odtwarzanie lub gdy zmienia się parametr 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ą takie zdarzenia, jak wstrzymanie, odtworzenie, wznowienie lub wyszukiwanie, aplikacja będzie musiała podjąć działania i zsynchronizować się między sobą a aplikacją Web Odbiornik na urządzeniu Cast. Więcej informacji znajdziesz w sekcji Aktualizacje stanu.

Jak działa zarządzanie sesjami

Pakiet SDK Cast przedstawia koncepcję sesji przesyłania, która łączy w sobie etapy łączenia się z urządzeniem, uruchamiania (lub dołączania) aplikacji internetowej odbiornika, łączenia się z nią i inicjowania kanału sterowania multimediami. Więcej informacji o sesjach przesyłania i cyklu życia odbiornika internetowego znajdziesz w przewodniku po cyklu życia aplikacji na odbiorniku internetowym.

Sesje są zarządzane przez klasę CastContext, którą aplikacja może pobrać za pomocą cast.framework.CastContext.getInstance(). Pojedyncze sesje są reprezentowane przez podklasy Session. Na przykład CastSession oznacza sesje z urządzeniami przesyłającymi. Aplikacja może uzyskać dostęp do obecnie aktywnej sesji przesyłania na stronie CastContext.getCurrentSession().

Aby monitorować stan sesji, dodaj do CastContext odbiornik 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;
    }
  })

Jeśli chcesz się rozłączyć, np. gdy użytkownik kliknie przycisk „Zatrzymaj przesyłanie” w oknie przesyłania, możesz dodać w swoim odbiorniku odbiornik zdarzenia RemotePlayerEventType.IS_CONNECTED_CHANGED. W odbiorniku sprawdź, czy RemotePlayer jest odłączony. Jeśli tak, odpowiednio 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 na platformie, ale sam 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);
}

Przenoszenie strumienia

Zachowanie stanu sesji jest podstawą przesyłania strumienia, w ramach którego użytkownicy mogą przenosić strumienie audio i wideo między urządzeniami za pomocą poleceń głosowych, aplikacji Google Home lub inteligentnych ekranów. Odtwarzanie multimediów zatrzymuje się na jednym urządzeniu (źródło), a następnie jest kontynuowane na innym (miejscu docelowym). Każde urządzenie przesyłające z najnowszym oprogramowaniem może służyć jako źródło lub miejsca docelowe w przesyłaniu strumieniowym.

Aby podczas przenoszenia strumienia uzyskać nowe urządzenie docelowe, wywołaj zdarzenie CastSession#getCastDevice() po wywołaniu zdarzenia cast.framework.SessionState.SESSION_RESUMED.

Więcej informacji znajdziesz w sekcji Przenoszenie strumienia w internetowym odbiorniku.

Wstecz
Konfiguracja
Dalej
Dodaj funkcje zaawansowane