Zintegruj SDK Cast z aplikacją Web Sender

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

Uwaga: zalecamy wypróbowanie tych rozwiązań:

• Samouczek Cast Web Sender – dowiedz się krok po kroku, jak zmodyfikować istniejącą aplikację internetową do odtwarzania filmów, aby odtwarzała treści na urządzeniu przesyłającym Google Cast.
• Aplikacja przykładowa CastVideos-chrome (GitHub) – uruchom, przejrzyj i wyświetl tę aplikację przykładową, która jest zgodna z wytycznymi dotyczącymi UX i listą kontrolną projektu.

Terminologia

Urządzenie mobilne lub przeglądarka to nadawca, który steruje odtwarzaniem. Urządzenie przesyłające Google Cast to odbiornik, który wyświetla treści na ekranie do odtwarzania.

Pakiet Web Sender SDK składa się z 2 części: interfejsu Framework API (cast.framework) i interfejsu Base API (chrome.cast) Zwykle wywołujesz prostszy interfejs Framework API wyższego poziomu, który jest następnie przetwarzany przez interfejs Base API niższego poziomu.

Platforma nadawcy to interfejs Framework API, moduł i powiązane zasoby, które zapewniają otoczkę dla funkcji niższego poziomu. Aplikacja nadawcy lub aplikacja Google Cast Chrome to aplikacja internetowa (HTML/JavaScript) działająca w przeglądarce Chrome na urządzeniu nadawcy. Aplikacja Web Receiver to aplikacja HTML/JavaScript działająca na Chromecaście lub urządzeniu przesyłającym 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 Google Cast Web Sender SDK, jak pokazano poniżej. Dodaj parametr zapytania URL loadCastFramework, aby wczytać też 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 Web Sender SDK używa przestrzeni nazw cast.framework.* . Przestrzeń nazw reprezentuje te elementy:

• 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 zawiera informacje o bieżącym stanie Cast i wywołuje zdarzenia dotyczące zmian stanu Cast i stanu sesji Cast.
• Obiekt CastSession zarządza sesją – zawiera 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 podany przycisk Cast nie wystarczy, możesz użyć stanu Cast, aby zaimplementować przycisk Cast.
• 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 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 programowo:

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

W razie potrzeby możesz zastosować do elementu dodatkowe style, np. rozmiar lub pozycjonowanie. Użyj atrybutu --connected-color, aby wybrać kolor dla stanu połączonego odbiornika internetowego, a --disconnected-color – dla stanu rozłączonego.

Zdarzenie inicjujące

Po wczytaniu interfejsu Framework API aplikacja wywoła obsługę window.__onGCastApiAvailable. Zanim wczytasz bibliotekę nadawcy, upewnij się, że aplikacja ustawiła tę obsługę w window.

W ramach tej obsługi zainicjuj interakcję Cast, wywołując metodę setOptions(options) w 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ę singleton obiektu CastContext udostępnianą 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żyj stałej predefiniowanej przez pakiet 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żącą CastSession za pomocą getCurrentSession().

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

Za pomocą CastSession można wczytywać multimedia na połączone urządzenie przesyłające 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 LoadRequest, ustawiając wszystkie istotne informacje dotyczące żądania. Na koniec wywołaj loadMedia(loadRequest) w 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 obietnicę , której można użyć do wykonania wszelkich niezbędnych operacji w przypadku pomyślnego wyniku. Jeśli obietnica zostanie odrzucona, argument funkcji będzie a chrome.cast.ErrorCode.

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

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

RemotePlayerController zapewnia aplikacji pełną kontrolę nad multimediami, w tym odtwarzanie, wstrzymywanie, zatrzymywanie i przewijanie wczytanych multimediów.

• ODTWARZANIE/WSTRZYMANIE: playerController.playOrPause();
• ZATRZYMANIE: playerController.stop();
• PRZEWIJANIE: playerController.seek();

RemotePlayer i RemotePlayerController można używać z platformami powiązań danych, takimi jak Polymer czy Angular, do implementowania 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 dla różnych cast.framework.RemotePlayerEventType zdarzeń w RemotePlayerControllerobiekcie.

Aby uzyskać informacje o stanie multimediów, użyj cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED zdarzenia, 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 przewijanie, aplikacja będzie musiała na nie reagować i synchronizować się z aplikacją Web Receiver na urządzeniu Cast. Więcej informacji znajdziesz w sekcji Aktualizacje stanu.

Jak działa zarządzanie sesjami

Pakiet Cast SDK wprowadza pojęcie sesji Cast, której utworzenie łączy kroki połączenia z urządzeniem, uruchomienia (lub dołączenia) aplikacji Web Receiver, połączenia z tą aplikacją i zainicjowania kanału sterowania multimediami. Więcej informacji o sesjach Cast i cyklu życia odbiornika internetowego znajdziesz w przewodniku Cykl życia aplikacji Web Receiver .

Sesje są zarządzane przez klasę 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 z urządzeniami Cast. Aplikacja może uzyskać dostęp do aktualnie aktywnej sesji Cast 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 dla typu zdarzenia RemotePlayerEventType.IS_CONNECTED_CHANGED w detektorze. W detektorze sprawdź, czy RemotePlayer jest rozłączony. Jeśli tak, w razie potrzeby zaktualizuj lokalny stan 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`.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ą przeniesienia odtwarzania, 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. Odtwarzanie multimediów zatrzymuje się na jednym urządzeniu (źródłowym) i jest kontynuowane na innym (docelowym). Każde urządzenie przesyłające z najnowszym oprogramowaniem układowym może służyć jako źródło lub miejsce docelowe w przypadku przeniesienia odtwarzania.

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

Więcej informacji znajdziesz w sekcji Przeniesienie odtwarzania w odbiorniku internetowym.