Migracja do odbiornika internetowego

Ten przewodnik wyjaśnia, jak przenieść odbiornik Cast w wersji 2 do najnowszej wersji.

Nowy pakiet SDK Cast Application Framework (CAF), znany również jako Web odbiornik w wersji 3, jest dużym uaktualnieniem pakietu SDK odbiornika w wersji 2. Web odbiornik SDK to łatwy w obsłudze, prosty pakiet SDK do tworzenia aplikacji internetowych odbiorników internetowych.

Web odbiornik API udostępnia interfejs API bardziej spójny z nowymi interfejsami API nadawców wiadomości CAF. Oferuje pełną integrację odtwarzacza (MPL i Shaka) oraz pełną implementację i obsługę poleceń głosowych Cast oraz poleceń głosowych Asystenta Google. Pakiet SDK CAF udostępnia też domyślny interfejs, który można łatwo dostosować za pomocą CSS, oraz usługę wiązania danych, która upraszcza implementację interfejsu.

Dlaczego warto przeprowadzić migrację?

Dzięki przeniesieniu aplikacji odbiornika w wersji 2 do odbiornika internetowego można wyeliminować wiele kodów obsługujących odtwarzacz, dzięki czemu można skoncentrować się na tworzeniu logiki biznesowej aplikacji.

CAF płynnie integruje odtwarzacze MPL i Shaka z obsługą różnych typów treści, w tym m.in. strumieniowania HTTP na żywo (TS i CMAF), MPEG-DASH, gładkiego odtwarzania oraz typów obsługiwanych przez usługę źródłową Media Element (MP3, MP4, Icecast itp.). Pełną listę znajdziesz w artykule Obsługiwane multimedia na Google Cast. Obecnie CAF nie obsługuje odtwarzacza przekazywanego przez użytkowników.

Przejście na CAF spowoduje obsługę sterowania głosem za pomocą Asystenta Google. Każde nowe polecenie głosowe Asystenta Google będzie automatycznie obsługiwane, gdy użyjesz pliku CAF.

Oprócz obsługi nowych poleceń multimedialnych, takich jak „zmieniaj utwory według języka” i „zmień szybkość odtwarzania”, CAF zapewnia też lepszą kolejkę, wbudowaną obsługę reklam i lepszą pomoc na żywo.

Co się zmieniło?

Interfejs Web odbiornika API jest zgodny z konwencjami wprowadzonymi przez nadawców CAF w przypadku Androida i iOS. I zupełnie różni się od wersji 2.

Web odbiornik korzysta z nowej przestrzeni nazw cast.framework zamiast cast.receiver przestrzeni nazw we wszystkich ujawnionych interfejsach API. Wiele obiektów danych używanych przez wersję 2 jest takich samych w CAF i są one wyświetlane w przestrzeni nazw cast.framework.messages (znajdowały się one zazwyczaj poniżej cast.receiver.media).

Poniższe usługi w wersji 2 są zastępowane odpowiednimi usługami CAF:

  • Klasa CastReceiverManager jest zastępowana przez identyfikator CastReceiverContext, który zarządza sesją przesyłania, nadawcami, wysyłaniem niestandardowych wiadomości i globalnymi zdarzeniami systemowymi. CastReceiverOptions może służyć do udostępniania kontekstu – globalnych opcji aplikacji (takich jak kolejka, wersja odbiornika, konfiguracja odtwarzania).
  • Klasa MediaManager jest zastępowana przez właściwość PlayerManager, która jest właściwością pojedynczego zasobu CastReceiverContext, zarządza zarządzaną sesją mediów, żądaniami multimediów, żądaniami głosowymi Asystenta Google (CommandAndControlManager w wersji 2) i wywołuje zdarzenia multimedialne. Konfigurację odtwarzaczy (cast.player.api.Host w MPL) dostarcza PlaybackConfig, który może być udostępniany globalnie lub według żądania wczytania.

PlayerManager udostępnia też nowe zajęcia podrzędne:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

// Set global options.
const options = new cast.framework.CastReceiverOptions();
options.versionCode = DEVELOPERS_APP_VERSION;

context.start(options);

Logika biznesowa odbiorcy

Moduły obsługi zdarzeń udostępniane w wersji 2 (np. CastReceiverManager.onReady lub MediaManager.onLoad) dodają logikę biznesową. W CAF moduły obsługi zdarzeń są zastępowane detektorami zdarzeń (CastReceiverContext.addEventListener) i funkcjami przechwytywania wiadomości (PlayerManager.setMessageInterceptor). Odbiornik internetowy może mieć wiele odbiorników zdarzeń (odbiornik nie ma wpływu na zdarzenie), a jeden przechwytujący na wiadomość. Element, który przechwycił, może zaktualizować lub obsłużyć żądanie (zwrócone zmodyfikowane żądanie, komunikat o powodzeniu lub komunikat o błędzie). Może też być asynchronicznym tagiem, który zwraca obietnicę.

Funkcja przechwytywania żądań wczytywania jest najczęściej stosowanym sposobem dodawania logiki aplikacji. W przypadku żądań obciążenia od nadawcy funkcja wczytywania obciążenia może przekonwertować identyfikator treści na adres URL zawartości. Funkcja przechwytywania wczytywania jest również wywoływana na potrzeby żądań wstępnego wczytywania i z pamięci podręcznej, jeśli nie określono żadnego elementu przechwytywania wstępnego dla wstępnego i pamięci podręcznej.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      // Resolve entity to content id
      if (request.media.entity && !request.media.contentId) {
        return getMediaByEntity(request.media.entity).then(
            media => {
              request.media.contentId = media.url;
              return request;
            });
      }
      return request;
    });

Niestandardowy moduł obsługi stanu multimediów w wersji 2 jest też zastępowany mechanizmem przechwytywania wiadomości dla tego stanu. Aplikacje korzystające z odbiornika internetowego, które nie chcą udostępniać adresu URL multimediów w stanie multimediów, mogą utworzyć resolver adresów URL (PlayerManager.setMediaUrlResolver), który podaje adres URL multimediów na potrzeby żądania wczytania. Ten adres jest używany wewnętrznie przez CAF i nie jest podawany w stanie multimediów.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.MEDIA_STATUS,
    status => {
      // Disable seek.
      status.supportedMediaCommands &=
          ~cast.framework.messages.Command.SEEK
      return status;
    });

Zdarzenia

Odbiornik internetowy udostępnia rozbudowany zestaw zdarzeń pochodzących z CastReceiverContext i PlayerManager. Aplikacje z odbiornikiem internetowym mogą mieć wiele odbiorników dla dowolnego zdarzenia, a także 1 odbiornik dla wielu zdarzeń. W przypadku niektórych grup wydarzeń informacje znajdziesz w sekcji cast.framework.events.category.

Zdarzenia obejmują wszystkie żądania użytkowników, postępy w odtwarzaniu, przetwarzanie odtwarzacza i wszystkie zdarzenia niskiego poziomu mediów (CAF nie ujawnia samego elementu multimedialnego).

Aplikacja Web odbiornik może dodawać detektory zdarzeń, aby podjąć działania (np. dodać definicję ścieżek tekstowych po zakończeniu wczytywania) lub na potrzeby statystyk.

// Log all media commands
playerManager.addEventListener(
    cast.framework.events.category.REQUEST,
    event => logEvent(event.type));

Niestandardowy komunikat

CAF nie ujawnia autobusu wiadomości w interfejsie API. Zamiast tego udostępnia metodę CastReceiverContext.addCustomMessageListener, która pozwala dodać odbiornik wiadomości dla określonej przestrzeni nazw (tylko 1 na przestrzeń nazw) oraz CastReceiverContext.sendCustomMessage, aby wysłać wiadomość w przestrzeni nazw. Wszystkie przestrzenie nazw muszą być zadeklarowane przed uruchomieniem odbiornika internetowego (czyli przed wywołaniem funkcji CastReceiverContext.start). Przestrzenie nazw można zadeklarować, dodając do nich odbiornik wiadomości lub podając je jako opcję startową w CastReceiverOptions.customNamespaces.

const options = new cast.framework.CastReceiverOptions();
options.customNamespaces = {
    CUSTOM_NS: cast.framework.system.MessageType.JSON
};
context.start(options);

context.sendCustomMessage(CUSTOM_NS, {
  type: 'status'
  message: 'Playing'
});

Domyślny interfejs użytkownika

CAF udostępnia domyślny interfejs internetowy odbiornika, który w razie potrzeby wyświetla pasek postępu odtwarzania i metadane multimediów. Domyślny interfejs użytkownika jest dostarczany jako element niestandardowy (<cast-media-player>), który można zmienić za pomocą stylu podobnego do CSS.

<style>
   cast-media-player { --splash-image: url("splash.png"); }
</style>
<cast-media-player></cast-media-player>

Aby zapewnić więcej możliwości dostosowania, aplikacja internetowa odbiornik może zaimplementować własny interfejs użytkownika. Odbiornik internetowy udostępnia klasę cast.framework.ui.PlayerDataBinder, która ułatwia powiązanie obiektu interfejsu użytkownika ze stanem odtwarzania.