Zintegruj SDK Cast z aplikacją Web Sender

Z tego przewodnika dla programistów dowiesz się, jak dodać obsługę Google Cast do aplikacji Web Sender za pomocą pakietu SDK Cast.

Terminologia

Urządzenie mobilne lub przeglądarka jest nadawcą, który steruje odtwarzaniem. Urządzenie Google Cast jest odbiornikiem, który wyświetla zawartość ekranu w celu odtworzenia.

Pakiet Web Sender SDK składa się z 2 części: interfejsu Framework API (cast.framework) i interfejsu Base API (chrome.cast). Ogólnie rzecz biorąc, wykonujesz wywołania prostszego interfejsu Framework API wyższego poziomu, który jest następnie przetwarzany przez interfejs Base API niższego poziomu.

Platforma nadawcy odnosi się do interfejsu Framework API, modułu i powiązanych zasobów, które zapewniają otokę funkcji niższego poziomu. Określenie aplikacja nadawcy lub aplikacja Google Cast na Chrome odnosi się do aplikacji internetowej (HTML/JavaScript) uruchomionej w przeglądarce Chrome na urządzeniu nadawcy. Aplikacja Web Receiver to aplikacja HTML/JavaScript działająca na Chromecaście lub urządzeniu Google Cast.

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

Wczytaj bibliotekę

Aby aplikacja obsługiwała funkcje Google Cast, musi znać lokalizację pakietu Google Cast Web Sender SDK (jak pokazano poniżej). Aby wczytać też interfejs Web Sender Framework API, dodaj parametr zapytania URL loadCastFramework. Wszystkie strony aplikacji muszą odnosić się do biblioteki w ten sposób:

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

Platforma

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

  • Metody lub funkcje, które wywołują operacje na interfejsie API
  • Detektory zdarzeń dla funkcji odbiornika w interfejsie API

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

  • CastContext to pojedynczy obiekt, który dostarcza informacje 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 wywołuje zdarzenia, takie jak zmiany głośności urządzenia, stan wyciszenia i metadane aplikacji.
  • Przycisk Cast – prosty niestandardowy element HTML, który rozszerza przycisk HTML. Jeśli dostarczony przycisk przesyłania jest niewystarczający, możesz go zaimplementować, używając stanu przesyłania.
  • RemotePlayerController umożliwia powiązanie danych, co upraszcza implementację odtwarzacza zdalnego.

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

Przycisk Cast

Komponent przycisku przesyłania 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 do elementu możesz zastosować dowolne dodatkowe style, takie jak rozmiar lub umiejscowienie. Użyj atrybutu --connected-color, aby wybrać kolor stanu połączonego odbiornika internetowego, a --disconnected-color – stan braku połączenia.

Zdarzenie inicjujące

Po wczytaniu interfejsu API platformy aplikacja wywoła moduł obsługi window.__onGCastApiAvailable. Upewnij się, że aplikacja ustawi ten moduł obsługi w window, zanim załaduje bibliotekę nadawcy.

W tym module obsługi zainicjujesz interakcję przesyłania, wywołując metodę setOptions(options) CastContext.

Na przykład:

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

Następnie inicjujesz 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 dostarczonego przez platformę. Następnie używa setOptions(options) za pomocą obiektu CastOptions do ustawienia applicationID.

Jeśli używasz domyślnego odbiornika multimediów, który nie wymaga rejestracji, zamiast zasady applicationID użyj stałej wartości 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 obiektu CastContext aplikacja może w każdej chwili pobrać bieżącą wartość CastSession za pomocą getCurrentSession().

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

Za pomocą CastSession można ładować multimedia do połączonego urządzenia przesyłającego za pomocą loadMedia(loadRequest). Najpierw utwórz MediaInfo, używając elementów contentId i contentType, a także wszelkich innych informacji związanych z treścią. Następnie utwórz na jego podstawie LoadRequest, zawierający wszystkie informacje związane z żądaniem. Na koniec wywołaj połączenie loadMedia(loadRequest) na 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 element Promise, którego można użyć do wykonania niezbędnych operacji do uzyskania pożądanego 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ń multimediów, są obsługiwane za pomocą interfejsu RemotePlayerController.

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

RemotePlayerController daje aplikacji pełną kontrolę nad wczytywanymi multimediami: PLAY, PAUSE, STOP i SEEK.

  • ODTWÓRZ/WSTRZYMAJ: playerController.playOrPause();
  • ZATRZYMAJ: playerController.stop();
  • WYSZUKIWANIE: playerController.seek();

Obiektów RemotePlayer i RemotePlayerController można używać z platformami wiązania danych, takimi jak Polymer czy Angular, do implementacji odtwarzacza zdalnego.

Oto fragment kodu 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 mają miejsce różne zdarzenia, które można przechwytywać przez ustawienie detektorów 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 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ępują zdarzenia takie jak wstrzymanie, odtworzenie, wznowienie lub przewijanie, aplikacja musi wykonać odpowiednie działania i zsynchronizować się między swoją aplikacją a aplikacją Web Receiver na urządzeniu przesyłającym. Więcej informacji znajdziesz w sekcji Aktualizacje stanu.

Jak działa zarządzanie sesjami

W ramach pakietu Cast SDK wprowadzamy koncepcję sesji przesyłania, która obejmuje etapy łączenia się z urządzeniem, uruchamiania (lub dołączania) aplikacji odbiornika internetowego oraz łą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.

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

Aby monitorować stan sesji, dodaj do obiektu CastContext detektor 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 odłączyć urządzenie, na przykład gdy kliknie on przycisk „Zatrzymaj przesyłanie” w oknie przesyłania, możesz dodać do detektora typ zdarzenia RemotePlayerEventType.IS_CONNECTED_CHANGED. W detektorze sprawdź, czy konto RemotePlayer jest odłączone. Jeśli tak, w razie potrzeby 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 przesyłania platformy, ale sam nadawca może zatrzymać przesyłanie przy użyciu 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ą przenoszenia strumienia, w ramach której 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. Multimedia zatrzymują się na jednym urządzeniu (źródle) i na drugim (miejscu docelowym). Każde urządzenie przesyłające z najnowszym oprogramowaniem może służyć jako źródło lub miejsce docelowe podczas przesyłania strumienia.

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

Więcej informacji znajdziesz w sekcji Przesyłanie strumienia w internetowym odbiorniku.

Wstecz
Konfiguracja
Dalej
Dodaj funkcje zaawansowane