Zintegruj SDK Cast z aplikacją Web Sender

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

Terminologia

Urządzenie mobilne lub przeglądarka to nadawca, który kontroluje odtwarzanie. Urządzenie Google Cast to odbiornik, który wyświetla treści na ekranie.

Pakiet SDK przesyłającego na potrzeby Internetu składa się z 2 części: interfejsu Framework API (cast.framework) i interfejsu Base API (chrome.cast). Zazwyczaj wywołujesz interfejs Framework API o prostszej strukturze na wyższym poziomie, który jest następnie przetwarzany przez interfejs Base API na niższym poziomie.

Framework nadawcy to interfejs Framework API, moduł i powiązane zasoby, które stanowią otulinę dla funkcji niskiego poziomu. Aplikacja nadawcy lub aplikacja Google Cast w Chrome to aplikacja internetowa (HTML/JavaScript) uruchamiana w przeglądarce Chrome na urządzeniu nadawcy. Aplikacja Web Receiver to aplikacja HTML/JavaScript działająca na Chromecastzie lub urządzeniu Google Cast.

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

Wczytywanie biblioteki

Aby aplikacja mogła implementować funkcje Google Cast, musi znać lokalizację pakietu SDK Google Cast Web Sender, jak pokazano poniżej. Dodaj parametr zapytania URL loadCastFramework, aby załadować interfejs Web Sender Framework API. Wszystkie strony aplikacji muszą odwoływać 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 SDK nadawcy internetowego używa przestrzeni nazw cast.framework.*. Przestrzeń nazw reprezentuje:

• metody lub funkcje wywołujące operacje w interfejsie API;
• Detektory zdarzeń dla funkcji detektorów w interfejsie API

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

• CastContextto obiekt typu singleton, który zawiera informacje o bieżącym stanie Cast i wyzwala zdarzenia dotyczące zmian stanu Cast oraz stanu sesji Cast.
• Obiekt CastSession zarządza sesją – dostarcza informacje o stanie i uruchamia zdarzenia, takie jak zmiany głośności urządzenia, stan wyciszenia i metadane aplikacji.
• Element przycisku Cast, czyli prosty element niestandardowy HTML, który rozszerza przycisk HTML. Jeśli udostępniony przycisk Cast nie wystarcza, możesz zaimplementować przycisk Cast, korzystając z stanu przesyłania.
• Element RemotePlayerController zapewnia powiązanie danych, aby uprościć 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 wyłącznie przez framework. Obejmuje to zarządzanie widocznością oraz obsługę zdarzeń kliknięcia.

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

Możesz też utworzyć przycisk za pomocą kodu:

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

W razie potrzeby możesz zastosować do elementu dodatkowy styl, np. rozmiar lub położenie. Użyj atrybutu --connected-color, aby wybrać kolor dla stanu połączonego odbiornika internetowego i --disconnected-color dla stanu odłączonego.

Zdarzenie inicjujące

Po załadowaniu interfejsu API frameworku aplikacja wywoła element obsługi window.__onGCastApiAvailable. Upewnij się, że aplikacja ustawia ten moduł na window przed wczytaniem biblioteki nadawcy.

W ramach tego modułu 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 inicjuj 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ę singleton obiektu CastContext udostępnianego przez framework. Następnie używa parametru setOptions(options), korzystając z obiektu CastOptions, aby ustawić parametr applicationID.

Jeśli używasz domyślnego odbiornika multimediów, który nie wymaga rejestracji, zamiast applicationID użyj stałej wartości zdefiniowanej przez pakiet SDK nadawcy internetowego:

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

Sterowanie multimediami

Po zainicjowaniu CastContext aplikacja może w dowolnym momencie pobrać bieżącą wartość CastSession za pomocą getCurrentSession().

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

CastSession można używać do wczytywania multimediów na połączone urządzenie Cast za pomocą loadMedia(loadRequest). Najpierw utwórz MediaInfo, używając informacji contentId i contentType oraz wszelkich innych informacji związanych z treściami. Następnie utwórz na jego podstawie plik LoadRequest, podając wszystkie istotne informacje dotyczące prośby. Na koniec wywołaj funkcję loadMedia(loadRequest) w 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 zwróci obietnice, której można użyć do wykonania wszelkich niezbędnych operacji w celu uzyskania pożądanego wyniku. Jeśli obietnica zostanie odrzucona, argument funkcji będzie miał wartość chrome.cast.ErrorCode.

Dostęp do zmiennych stanu odtwarzacza masz w pliku RemotePlayer. Wszystkie interakcje z RemotePlayer, w tym wywołania zwrotne zdarzeń multimediów i polecenia, są obsługiwane przez RemotePlayerController.

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

RemotePlayerController pozwala aplikacji w pełni kontrolować odtwarzanie multimediów: PLAY, PAUSE, STOP i SEEK dla załadowanych multimediów.

• PLAY/PAUSE (odtwarzanie/wstrzymanie): playerController.playOrPause();
• STOP: playerController.stop();
• SEEK: playerController.seek();

Funkcji RemotePlayer i RemotePlayerController można używać z ramkami powiązań danych, takimi jak Polymer czy Angular, aby zaimplementować odtwarzacz zdalny.

Oto fragment kodu w przypadku 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 rejestrować, ustawiając listenery 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 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ąpią zdarzenia takie jak wstrzymanie, odtwarzanie, wznowienie lub przewijanie, aplikacja będzie musiała na nie reagować i synchronizować się z aplikacją Web Receiver na urządzeniu z Cast. Więcej informacji znajdziesz w aktualizacjach stanu.

Jak działa zarządzanie sesjami

Pakiet SDK Cast wprowadza pojęcie sesji Cast, której utworzenie łączy w sobie czynności takie jak połączenie z urządzeniem, uruchomienie (lub dołączenie) aplikacji Web Receiver, połączenie z tą aplikacją i inicjowanie 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, 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 Cast. Aplikacja może uzyskać dostęp do bieżącej sesji Cast za pomocą CastContext.getCurrentSession().

Aby monitorować stan sesji, dodaj detektor do zdarzenia 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 przesyłania, możesz dodać detektor dla typu zdarzenia RemotePlayerEventType.IS_CONNECTED_CHANGED. W słuchawce sprawdź, czy RemotePlayer jest rozłączona. 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, ale nadawca może też 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 stanowi podstawę przenoszenia strumienia, dzięki czemu 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 przestają być odtwarzane na jednym urządzeniu (źródło) i kontynuują na drugim (miejsce docelowe). Źródłem lub celem przesyłania strumieniowego może być dowolne urządzenie Cast z najnowszą wersją oprogramowania układowego.

Aby podczas przesyłania strumienia uzyskać nowe urządzenie docelowe, wywołaj funkcję CastSession#getCastDevice(), gdy zostanie wywołane zdarzenie cast.framework.SessionState.SESSION_RESUMED.

Więcej informacji znajdziesz w artykule Przenoszenie strumienia na odbiornik internetowy.