Dodaj podstawowe funkcje do niestandardowego odbiornika internetowego

Ta strona zawiera fragmenty kodu i opisy funkcji dostępnych w aplikacji niestandardowego odbiornika internetowego.

Uwaga: zalecamy wykonanie tych czynności:

• Samouczek dotyczący programowania aplikacji Cast Web Receiver – dowiedz się krok po kroku, jak utworzyć aplikację Web Receiver obsługującą Cast za pomocą pakietu Google Cast SDK, która może odbierać przesyłane filmy.
• Przykładowa aplikacja CastReceiver (GitHub) – uruchom, przeglądaj i wyświetlaj tę przykładową aplikację referencyjną, która jest zgodna ze wskazówkami dotyczącymi UX i listą kontrolną projektowania.

1. Element cast-media-player, który reprezentuje wbudowany interfejs odtwarzacza dostarczany z odbiornikiem internetowym.
2. Niestandardowy styl podobny do CSS dla elementu cast-media-player, który umożliwia stylizowanie różnych elementów interfejsu, takich jak background-image, splash-image i font-family.
3. Element skryptu do wczytywania platformy odbiornika internetowego.
4. kod JavaScriptu do przechwytywania wiadomości i obsługi zdarzeń.
5. Dodaj do kolejki autoodtwarzania.
6. Opcje konfiguracji odtwarzania.
7. Opcje ustawiania kontekstu odbiornika internetowego.
8. Opcje ustawiania poleceń obsługiwanych przez aplikację odbiornika internetowego.
9. Wywołanie JavaScriptu, które uruchamia aplikację odbiornika internetowego.

Uwaga: zdecydowanie zalecamy używanie elementu HTML cast-media-player, ponieważ obsługuje on cały stan interfejsu odtwarzacza wraz z jego stylem.

Konfiguracja i opcje aplikacji

Konfigurowanie aplikacji

CastReceiverContext to najbardziej zewnętrzna klasa udostępniana deweloperowi. Zarządza ona wczytywaniem podstawowych bibliotek i obsługuje inicjowanie pakietu SDK odbiornika internetowego. Pakiet SDK udostępnia interfejsy API, które umożliwiają deweloperom aplikacji konfigurowanie pakietu SDK za pomocą CastReceiverOptions. Te konfiguracje są oceniane raz przy każdym uruchomieniu aplikacji i przekazywane do pakietu SDK podczas ustawiania opcjonalnego parametru w wywołaniu start.

Poniższy przykład pokazuje, jak zastąpić działanie domyślne wykrywania, czy połączenie nadawcy jest nadal aktywne. Jeśli odbiornik internetowy nie może skomunikować się z nadawcą przez maxInactivity s, wysyłane jest zdarzenie SENDER_DISCONNECTED. Konfiguracja poniżej zastępuje ten limit czasu. Może to być przydatne podczas debugowania, ponieważ zapobiega zamykaniu sesji zdalnego debugera Chrome przez aplikację odbiornika internetowego, gdy nie ma połączonych nadawców w stanie IDLE.

Uwaga: w produkcyjnych aplikacjach Web Receiver należy unikać ustawiania maxInactivity i zamiast tego polegać na wartości domyślnej.

const context = cast.framework.CastReceiverContext.getInstance();
const options = new cast.framework.CastReceiverOptions();
options.maxInactivity = 3600; // Development only
context.start(options);

Konfigurowanie odtwarzacza

Podczas wczytywania treści pakiet SDK odbiornika internetowego umożliwia skonfigurowanie zmiennych odtwarzania, takich jak informacje o DRM, konfiguracje ponownych prób i moduły obsługi żądań, za pomocą cast.framework.PlaybackConfig. Te informacje są obsługiwane przez PlayerManager i oceniane w momencie tworzenia odtwarzaczy. Odtwarzacze są tworzone za każdym razem, gdy do pakietu SDK odbiornika internetowego jest przekazywane nowe żądanie wczytania. Zmiany wprowadzone w PlaybackConfig po utworzeniu odtwarzacza są oceniane podczas następnego wczytywania treści. Pakiet SDK udostępnia te metody modyfikowania PlaybackConfig.

• CastReceiverOptions.playbackConfig, aby zastąpić domyślne opcje konfiguracji podczas inicjowania CastReceiverContext.
• PlayerManager.getPlaybackConfig(), aby uzyskać bieżącą konfigurację.
• PlayerManager.setPlaybackConfig(), aby zastąpić bieżącą konfigurację. To ustawienie jest stosowane do wszystkich kolejnych wczytań lub do momentu, gdy zostanie ponownie zastąpione.
• PlayerManager.setMediaPlaybackInfoHandler(), aby zastosować dodatkowe konfiguracje tylko do wczytywanego elementu multimedialnego, oprócz bieżących konfiguracji. Moduł obsługi jest wywoływany tuż przed utworzeniem odtwarzacza. Wprowadzone tutaj zmiany nie są trwałe i nie są uwzględniane w zapytaniach do getPlaybackConfig(). Gdy zostanie wczytany następny element multimedialny, ten moduł obsługi zostanie wywołany ponownie.

Poniższy przykład pokazuje, jak ustawić PlaybackConfig podczas inicjowania CastReceiverContext. Konfiguracja zastępuje żądania wychodzące dotyczące uzyskiwania plików manifestu. Moduł obsługi określa, że żądania CORS Access-Control powinny być wysyłane przy użyciu danych logowania, takich jak pliki cookie lub nagłówki autoryzacji.

const playbackConfig = new cast.framework.PlaybackConfig();
playbackConfig.manifestRequestHandler = requestInfo => {
  requestInfo.withCredentials = true;
};
context.start({playbackConfig: playbackConfig});

Poniższy przykład pokazuje, jak zastąpić PlaybackConfig za pomocą metody pobierającej i ustawiającej podanej w PlayerManager. To ustawienie konfiguruje odtwarzacz tak, aby wznawiał odtwarzanie treści po wczytaniu 1 segmentu.

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
const playbackConfig = (Object.assign(
            new cast.framework.PlaybackConfig(), playerManager.getPlaybackConfig()));
playbackConfig.autoResumeNumberOfSegments = 1;
playerManager.setPlaybackConfig(playbackConfig);

Poniższy przykład pokazuje, jak zastąpić PlaybackConfig w przypadku konkretnego żądania wczytania za pomocą modułu obsługi informacji o odtwarzaniu multimediów. Moduł obsługi wywołuje metodę zaimplementowaną przez aplikację getLicenseUrlForMedia, aby uzyskać licenseUrl z contentId bieżącego elementu.

playerManager.setMediaPlaybackInfoHandler((loadRequestData, playbackConfig) => {
  const mediaInformation = loadRequestData.media;
  playbackConfig.licenseUrl = getLicenseUrlForMedia(mediaInformation.contentId);

  return playbackConfig;
});

Detektor zdarzeń

Pakiet SDK odbiornika internetowego umożliwia aplikacji odbiornika internetowego obsługę zdarzeń odtwarzacza. Detektor zdarzeń przyjmuje parametr cast.framework.events.EventType (lub tablicę tych parametrów), który określa zdarzenia, które powinny aktywować detektor. Wstępnie skonfigurowane tablice cast.framework.events.EventType, które są przydatne do debugowania, znajdziesz w cast.framework.events.category. Parametr zdarzenia dostarcza dodatkowych informacji o zdarzeniu.

Jeśli na przykład chcesz wiedzieć, kiedy jest transmitowana zmiana mediaStatus, możesz użyć tej logiki do obsługi zdarzenia:

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
playerManager.addEventListener(
    cast.framework.events.EventType.MEDIA_STATUS, (event) => {
      // Write your own event handling code, for example
      // using the event.mediaStatus value
});

Uwaga: platforma odbiornika internetowego automatycznie śledzi, kiedy nadawca się z nią łączy lub rozłącza, i nie wymaga jawnego detektora zdarzeń SENDER_DISCONNECTED w logice odbiornika internetowego.

Przechwytywanie wiadomości

Pakiet SDK odbiornika internetowego umożliwia aplikacji odbiornika internetowego przechwytywanie wiadomości i wykonywanie na nich niestandardowego kodu. Przechwytywacz wiadomości przyjmuje parametr cast.framework.messages.MessageType, który określa, jaki typ wiadomości ma zostać przechwycony.

Przechwytywacz powinien zwracać zmodyfikowane żądanie lub obiekt Promise, który rozwiązuje się ze zmodyfikowaną wartością żądania. Zwrócenie wartości null uniemożliwi wywołanie domyślnego modułu obsługi wiadomości. Więcej informacji znajdziesz w sekcji Wczytywanie multimediów.

Jeśli na przykład chcesz zmienić dane żądania wczytania, możesz użyć tej logiki, aby je przechwycić i zmodyfikować:

Uwaga: nie dodawaj ani nie modyfikuj właściwości queueData obiektu LoadRequestData w interceptorze LOAD. Nie będzie to miało wpływu na odtwarzanie, ponieważ element queueData został już odczytany i zastosowany do kolejki. Więcej informacji znajdziesz w przewodniku po kolejkowaniu.

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

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_FAILED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      if (!loadRequestData.media.entity) {
        return loadRequestData;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          if (!asset) {
            throw cast.framework.messages.ErrorReason.INVALID_REQUEST;
          }

          loadRequestData.media.contentUrl = asset.url;
          loadRequestData.media.metadata = asset.metadata;
          loadRequestData.media.tracks = asset.tracks;
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

context.start();

Obsługa błędów

Gdy w przechwytywaczu wiadomości wystąpią błędy, aplikacja odbiornika internetowego powinna zwrócić odpowiednie wartości cast.framework.messages.ErrorType i cast.framework.messages.ErrorReason.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_CANCELLED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      ...

      return fetchAssetAndAuth(loadRequestData.media.entity,
                               loadRequestData.credentials)
        .then(asset => {
          ...
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

Przechwytywanie wiadomości a detektor zdarzeń

Oto niektóre z najważniejszych różnic między przechwytywaniem wiadomości a detektorem zdarzeń:

• Detektor zdarzeń nie pozwala na modyfikowanie danych żądania.
• Detektor zdarzeń najlepiej sprawdza się do uruchamiania funkcji analitycznych lub niestandardowych.

Uwaga: detektor zdarzeń może też służyć do nasłuchiwania grupy zdarzeń za pomocą typu wyliczeniowego CORE, DEBUG lub FINE.

playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });

• Przechwytywanie wiadomości umożliwia nasłuchiwanie wiadomości, przechwytywanie jej i modyfikowanie samych danych żądania.
• Przechwytywanie wiadomości najlepiej sprawdza się w przypadku obsługi niestandardowej logiki dotyczącej danych żądania.

Wczytuję multimedia

MediaInformation udostępnia wiele właściwości do wczytywania multimediów w wiadomości cast.framework.messages.MessageType.LOAD, w tym entity, contentUrl i contentId.

• Właściwość entity jest zalecana do użycia w implementacji zarówno w aplikacji nadawcy, jak i odbiorcy. Właściwość jest adresem URL precyzyjnego linku, który może być playlistą lub treściami multimedialnymi. Aplikacja powinna przeanalizować ten adres URL i wypełnić co najmniej jedno z pozostałych 2 pól.
• Wartość contentUrl odpowiada adresowi URL, którego odtwarzacz użyje do wczytania treści. Ten adres URL może na przykład wskazywać plik manifestu DASH.
• Właściwość contentId może być adresem URL treści, które można odtworzyć (podobnie jak właściwość contentUrl), lub unikalnym identyfikatorem treści albo playlisty, które są wczytywane. Jeśli używasz tej właściwości jako identyfikatora, aplikacja powinna wypełnić adres URL do odtworzenia w polu contentUrl.

Zalecamy używanie entity do przechowywania prawdziwego identyfikatora lub kluczowych parametrów oraz contentUrl do adresu URL multimediów. Przykładem jest ten fragment kodu, w którym parametr entity jest obecny w żądaniu LOAD, a odtwarzany jest parametr contentUrl:

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      ...

      if (!loadRequestData.media.entity) {
        // Copy the value from contentId for legacy reasons if needed
        loadRequestData.media.entity = loadRequestData.media.contentId;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          loadRequestData.media.contentUrl = asset.url;
          ...
          return loadRequestData;
        });
    });

Funkcje urządzenia

Metoda getDeviceCapabilities dostarcza informacji o połączonym urządzeniu Cast oraz podłączonym do niego urządzeniu wideo lub audio. Metoda getDeviceCapabilities dostarcza informacje o obsłudze Asystenta Google, Bluetootha oraz połączonych urządzeń wyświetlających i audio.

Ta metoda zwraca obiekt, który możesz odpytać, przekazując jeden z określonych typów wyliczeniowych, aby uzyskać możliwości urządzenia dla tego typu wyliczeniowego. Typy wyliczeniowe są zdefiniowane w pliku cast.framework.system.DeviceCapabilities.

W tym przykładzie sprawdzamy, czy urządzenie z odbiornikiem internetowym może odtwarzać treści HDR i DolbyVision (DV) za pomocą klawiszy IS_HDR_SUPPORTED i IS_DV_SUPPORTED.

const context = cast.framework.CastReceiverContext.getInstance();
context.addEventListener(cast.framework.system.EventType.READY, () => {
  const deviceCapabilities = context.getDeviceCapabilities();
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED] value
  }
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED] value
  }
});
context.start();

Obsługa interakcji użytkownika

Użytkownik może wchodzić w interakcje z aplikacją odbiornika internetowego za pomocą aplikacji nadawcy (internetowych, na Androida i iOS), poleceń głosowych na urządzeniach z Asystentem, sterowania dotykowego na inteligentnych ekranach i pilotów na urządzeniach z Androidem TV. Pakiet Cast SDK udostępnia różne interfejsy API, które umożliwiają aplikacji odbiornika internetowego obsługę tych interakcji, aktualizowanie interfejsu aplikacji za pomocą stanów działań użytkownika i opcjonalnie wysyłanie zmian w celu aktualizacji usług backendu.

Obsługiwane polecenia dotyczące multimediów

Stany elementów sterujących interfejsu są określane przez MediaStatus.supportedMediaCommands w przypadku rozszerzonych kontrolerów nadawcy na iOS i Androida, aplikacji odbiornika i pilota działających na urządzeniach dotykowych oraz aplikacji odbiornika na urządzeniach z Androidem TV. Gdy w usłudze włączona jest określona operacja bitowa Command, przyciski powiązane z tym działaniem są włączone. Jeśli wartość nie jest ustawiona, przycisk jest wyłączony. Te wartości można zmienić w odbiorniku internetowym przez:

1. Używanie PlayerManager.setSupportedMediaCommands do ustawiania konkretnego Commands
2. Dodawanie nowego polecenia za pomocą addSupportedMediaCommands
3. Usuwanie istniejącego polecenia za pomocą removeSupportedMediaCommands.

playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
  cast.framework.messages.Command.PAUSE);

Gdy odbiorca przygotuje zaktualizowany plik MediaStatus, będzie on zawierać zmiany we właściwości supportedMediaCommands. Po przesłaniu stanu połączone aplikacje nadawcze odpowiednio zaktualizują przyciski w swoim interfejsie.

Uwaga: zmiany wprowadzone w supportedMediaCommands nie spowodują zmiany typu wyświetlanego przycisku. Są one ustawiane bezpośrednio w aplikacjach nadawców (iOS, Android) i interfejsie API Controls odbiorcy. Jedynym wyjątkiem, w którym do wprowadzania tych zmian używana jest funkcja supportedMediaCommands, są karty odtwarzania multimediów na ekranie głównym inteligentnych ekranów.

Więcej informacji o obsługiwanych poleceniach multimedialnych i urządzeniach dotykowych znajdziesz w przewodniku Accessing UI controls.

Zarządzanie stanami działań użytkownika

Gdy użytkownicy wchodzą w interakcję z interfejsem lub wysyłają polecenia głosowe, mogą kontrolować odtwarzanie treści i właściwości związane z odtwarzanym elementem. Żądania sterujące odtwarzaniem są obsługiwane automatycznie przez pakiet SDK. Żądania, które modyfikują właściwości aktualnie odtwarzanego elementu, takie jak polecenie LIKE, wymagają, aby aplikacja odbiornika je obsługiwała. Pakiet SDK udostępnia serię interfejsów API do obsługi tego typu żądań. Aby obsługiwać te żądania, należy wykonać te czynności:

• Podczas wczytywania elementu multimedialnego ustaw MediaInformation userActionStates zgodnie z preferencjami użytkownika.
• Przechwytywanie wiadomości USER_ACTION i określanie żądanego działania.
• Zaktualizuj MediaInformation UserActionState, aby zaktualizować interfejs.

Uwaga: w razie potrzeby możesz POST działanie do odpowiednich backendów, aby zachować preferencje użytkownika.

Ten fragment kodu przechwytuje żądanie LOAD i wypełnia MediaInformation elementu LoadRequestData. W tym przypadku użytkownikowi podoba się wczytywana treść.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      const userActionLike = new cast.framework.messages.UserActionState(
          cast.framework.messages.UserAction.LIKE);
      loadRequestData.media.userActionStates = [userActionLike];

      return loadRequestData;
    });

Poniższy fragment kodu przechwytuje wiadomość USER_ACTION i obsługuje wywołanie backendu z żądaną zmianą. Następnie wywołuje funkcję, aby zaktualizować UserActionState na odbiorniku.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.USER_ACTION,
  (userActionRequestData) => {
    // Obtain the media information of the current content to associate the action to.
    let mediaInfo = playerManager.getMediaInformation();

    // If there is no media info return an error and ignore the request.
    if (!mediaInfo) {
        console.error('Not playing media, user action is not supported');
        return new cast.framework.messages.ErrorData(messages.ErrorType.BAD_REQUEST);
    }

    // Reach out to backend services to store user action modifications. See sample below.
    return sendUserAction(userActionRequestData, mediaInfo)

    // Upon response from the backend, update the client's UserActionState.
    .then(backendResponse => updateUserActionStates(backendResponse))

    // If any errors occurred in the backend return them to the cast receiver.
    .catch((error) => {
      console.error(error);
      return error;
    });
});

Poniższy fragment kodu symuluje wywołanie usługi backendu. Funkcja sprawdza UserActionRequestData, aby zobaczyć typ zmiany, o którą poprosił użytkownik, i wywołuje sieć tylko wtedy, gdy działanie jest obsługiwane przez backend.

function sendUserAction(userActionRequestData, mediaInfo) {
  return new Promise((resolve, reject) => {
    switch (userActionRequestData.userAction) {
      // Handle user action changes supported by the backend.
      case cast.framework.messages.UserAction.LIKE:
      case cast.framework.messages.UserAction.DISLIKE:
      case cast.framework.messages.UserAction.FOLLOW:
      case cast.framework.messages.UserAction.UNFOLLOW:
      case cast.framework.messages.UserAction.FLAG:
      case cast.framework.messages.UserAction.SKIP_AD:
        let backendResponse = {userActionRequestData: userActionRequestData, mediaInfo: mediaInfo};
        setTimeout(() => {resolve(backendResponse)}, 1000);
        break;
      // Reject all other user action changes.
      default:
        reject(
          new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType.INVALID_REQUEST));
    }
  });
}

Poniższy fragment kodu pobiera UserActionRequestData i dodaje lub usuwa UserActionState z MediaInformation. Aktualizacja UserActionState elementu MediaInformation zmienia stan przycisku powiązanego z żądanym działaniem. Ta zmiana jest odzwierciedlona w interfejsie sterowania inteligentnym wyświetlaczem, aplikacji do zdalnego sterowania i interfejsie Androida TV. Jest też transmitowany za pomocą wiadomości wychodzących MediaStatus, aby zaktualizować interfejs rozszerzonego kontrolera dla nadawców na iOS i Androidzie.

function updateUserActionStates(backendResponse) {
  // Unwrap the backend response.
  let mediaInfo = backendResponse.mediaInfo;
  let userActionRequestData = backendResponse.userActionRequestData;

  // If the current item playing has changed, don't update the UserActionState for the current item.
  if (playerManager.getMediaInformation().entity !== mediaInfo.entity) {
    return;
  }

  // Check for existing userActionStates in the MediaInformation.
  // If none, initialize a new array to populate states with.
  let userActionStates = mediaInfo.userActionStates || [];

  // Locate the index of the UserActionState that will be updated in the userActionStates array.
  let index = userActionStates.findIndex((currUserActionState) => {
    return currUserActionState.userAction == userActionRequestData.userAction;
  });

  if (userActionRequestData.clear) {
    // Remove the user action state from the array if cleared.
    if (index >= 0) {
      userActionStates.splice(index, 1);
    }
    else {
      console.warn("Could not find UserActionState to remove in MediaInformation");
    }
  } else {
    // Add the UserActionState to the array if enabled.
    userActionStates.push(
      new cast.framework.messages.UserActionState(userActionRequestData.userAction));
  }

  // Update the UserActionState array and set the new MediaInformation
  mediaInfo.userActionStates = userActionStates;
  playerManager.setMediaInformation(mediaInfo, true);
  return;
}

Polecenia głosowe

W pakiecie SDK odbiornika internetowego na urządzeniach z Asystentem obsługiwane są obecnie te polecenia multimedialne. Domyślne implementacje tych poleceń znajdziesz w pliku cast.framework.PlayerManager.

Polecenie	Opis
Google Play	Odtwarzanie lub wznawianie odtwarzania po wstrzymaniu.
Wstrzymywanie	Wstrzymaj odtwarzane treści.
Wstecz	Przejdź do poprzedniego elementu multimedialnego w kolejce.
Dalej	Przejdź do następnego elementu multimedialnego w kolejce.
Zatrzymaj	Zatrzymaj odtwarzanie multimediów.
Nie powtarzaj	Wyłącz powtarzanie elementów multimedialnych w kolejce po zakończeniu odtwarzania ostatniego elementu.
Powtarzaj pojedynczy	Powtarzaj odtwarzanie multimediów w nieskończoność.
Powtórz wszystko	Powtarzaj wszystkie elementy w kolejce po odtworzeniu ostatniego elementu.
Powtarzaj wszystko i odtwarzaj losowo	Po odtworzeniu ostatniego elementu w kolejce wymieszaj kolejkę i powtórz wszystkie elementy w kolejce.
Odtwarzanie losowe	Odtwarzaj elementy multimedialne w kolejce w losowej kolejności. Uwaga: możesz też odtwarzać multimedia w losowej kolejności przed odtworzeniem, używając flagi shuffle, jeśli jest ustawiona w loadRequestData wiadomości LOAD.
Włączanie i wyłączanie napisów	Włączanie i wyłączanie napisów w multimediach. Włączanie i wyłączanie jest też dostępne w zależności od języka.
Przewijanie do bezwzględnego czasu	Przechodzi do określonego czasu bezwzględnego.
Przewijanie do czasu względnego w stosunku do bieżącego czasu	Przeskakuje do przodu lub do tyłu o określony czas względem bieżącego czasu odtwarzania.
Zagraj ponownie	Ponownie odtwarza aktualnie odtwarzane multimedia lub odtwarza ostatnio odtwarzany element multimedialny, jeśli nic nie jest aktualnie odtwarzane.
Ustawianie szybkości odtwarzania	zmieniać szybkość odtwarzania multimediów, Ta sytuacja powinna być obsługiwana domyślnie. Aby zastąpić przychodzące żądania stawek, możesz użyć przechwytywacza wiadomości SET_PLAYBACK_RATE.

Obsługiwane polecenia głosowe dotyczące multimediów

Aby zapobiec wywoływaniu polecenia multimedialnego przez polecenie głosowe na urządzeniu z Asystentem, musisz najpierw ustawić obsługiwane polecenia multimedialne, które chcesz obsługiwać. Następnie musisz wymusić te polecenia, włączając właściwość CastReceiverOptions.enforceSupportedCommands. Interfejs nadawców Cast SDK i urządzeń dotykowych zmieni się, aby odzwierciedlić te konfiguracje. Jeśli flaga nie jest włączona, przychodzące polecenia głosowe będą wykonywane.

Jeśli na przykład zezwalasz na PAUSE z aplikacji nadawców i urządzeń dotykowych, musisz też skonfigurować odbiornik, aby odzwierciedlał te ustawienia. Po skonfigurowaniu wszystkie przychodzące polecenia głosowe będą odrzucane, jeśli nie znajdują się na liście obsługiwanych poleceń.

W przykładzie poniżej podajemy CastReceiverOptions podczas uruchamiania CastReceiverContext. Dodaliśmy obsługę polecenia PAUSE i wymusiliśmy na odtwarzaczu obsługę tylko tego polecenia. Jeśli polecenie głosowe zażąda innej operacji, np. SEEK, zostanie ono odrzucone. Użytkownik zostanie powiadomiony, że polecenie nie jest jeszcze obsługiwane.

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

context.start({
  enforceSupportedCommands: true,
  supportedCommands: cast.framework.messages.Command.PAUSE
});

Możesz zastosować osobną logikę do każdego polecenia, które chcesz ograniczyć. Usuń flagę enforceSupportedCommands i przechwyć wiadomość przychodzącą dla każdego polecenia, które chcesz ograniczyć. W tym miejscu przechwytujemy żądanie dostarczone przez pakiet SDK, aby polecenia SEEK wydawane urządzeniom z Asystentem nie powodowały przewijania w aplikacji odbiornika internetowego.

W przypadku poleceń multimedialnych, których aplikacja nie obsługuje, zwróć odpowiedni powód błędu, np. NOT_SUPPORTED.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.SEEK,
  seekData => {
    // Block seeking if the SEEK supported media command is disabled
    if (!(playerManager.getSupportedMediaCommands() & cast.framework.messages.Command.SEEK)) {
      let e = new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType
      .INVALID_REQUEST);
      e.reason = cast.framework.messages.ErrorReason.NOT_SUPPORTED;
      return e;
    }

    return seekData;
  });

Przełączanie w tło z aktywności głosowej

Jeśli platforma Cast wyciszy dźwięk aplikacji z powodu aktywności Asystenta, takiej jak słuchanie mowy użytkownika lub odpowiadanie, po rozpoczęciu aktywności do aplikacji Web Receiver zostanie wysłany komunikat FocusState o wartości NOT_IN_FOCUS. Po zakończeniu aktywności wysyłana jest kolejna wiadomość z IN_FOCUS. W zależności od aplikacji i odtwarzanych multimediów możesz wstrzymać odtwarzanie, gdy FocusState jest NOT_IN_FOCUS, przechwytując typ wiadomości FOCUS_STATE.

Na przykład dobrym rozwiązaniem jest wstrzymanie odtwarzania audiobooka, gdy Asystent odpowiada na zapytanie użytkownika.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.FOCUS_STATE,
  focusStateRequestData => {
    // Pause content when the app is out of focus. Resume when focus is restored.
    if (focusStateRequestData.state == cast.framework.messages.FocusState.NOT_IN_FOCUS) {
      playerManager.pause();
    } else {
      playerManager.play();
    }

    return focusStateRequestData;
  });

Język napisów określony głosowo

Jeśli użytkownik nie określi wyraźnie języka napisów, zostanie użyty język, w którym wypowiedziano polecenie. W takich przypadkach parametr isSuggestedLanguage wiadomości przychodzącej wskazuje, czy powiązany język został zasugerowany, czy wyraźnie zażądany przez użytkownika.

Na przykład isSuggestedLanguage jest ustawione na true dla polecenia „OK Google, włącz napisy”, ponieważ język został określony na podstawie języka, w którym wypowiedziano polecenie. Jeśli język jest wyraźnie określony, np. „OK Google, włącz napisy w języku angielskim”, parametr isSuggestedLanguage jest ustawiony na false.

Metadane i obsada głosowa

Polecenia głosowe są domyślnie obsługiwane przez odbiornik internetowy, ale musisz zadbać o to, aby metadane treści były kompletne i dokładne. Dzięki temu polecenia głosowe są prawidłowo obsługiwane przez Asystenta, a metadane są prawidłowo wyświetlane w nowych typach interfejsów, takich jak aplikacja Google Home i inteligentne ekrany, np. Google Home Hub.

Przeniesienie odtwarzania

Uwaga: odbiorniki internetowe audio domyślnie obsługują rozszerzenie odtwarzania, w ramach którego do sesji dodawane są kolejne urządzenia obsługujące Cast. Aby obsługiwać przenoszenie odtwarzania, odbiorniki internetowe wideo muszą wykonać czynności opisane w tej sekcji.

Zachowanie stanu sesji jest podstawą przenoszenia odtwarzania, dzięki któremu 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 zostanie zatrzymane na jednym urządzeniu (źródłowym) i będzie kontynuowane na innym (docelowym). Każde urządzenie Cast z najnowszym oprogramowaniem układowym może służyć jako źródło lub miejsce docelowe przeniesienia odtwarzania.

Przepływ zdarzeń podczas przenoszenia odtwarzania:

1. Na urządzeniu źródłowym:
   1. Odtwarzanie multimediów zostanie zatrzymane.
   2. Aplikacja odbiornika internetowego otrzymuje polecenie zapisania bieżącego stanu multimediów.
   3. Aplikacja odbiornika internetowego zostanie wyłączona.
2. Na urządzeniu docelowym:
   1. Aplikacja odbiornika internetowego została wczytana.
   2. Aplikacja odbiornika internetowego otrzymuje polecenie przywrócenia zapisanego stanu multimediów.
   3. Odtwarzanie multimediów zostanie wznowione.

Elementy stanu multimediów:

• określona pozycja lub sygnatura czasowa utworu, filmu lub elementu multimedialnego;
• miejsce w szerszej kolejce (np. na playliście lub w radiu wykonawcy).
• Uwierzytelniony użytkownik.
• stan odtwarzania (np. odtwarzanie lub wstrzymanie);

Włączanie przenoszenia odtwarzania

Aby wdrożyć przenoszenie odtwarzania w odbiorniku internetowym:

1. Zaktualizuj supportedMediaCommands za pomocą polecenia STREAM_TRANSFER:

   playerManager.addSupportedMediaCommands(
   cast.framework.messages.Command.STREAM_TRANSFER, true);

2. Opcjonalnie możesz zastąpić przechwytywacze wiadomości SESSION_STATE i RESUME_SESSION, jak opisano w sekcji Zachowywanie stanu sesji. Zastąp te wartości tylko wtedy, gdy dane niestandardowe muszą być przechowywane w ramach zrzutu sesji. W przeciwnym razie domyślna implementacja zachowywania stanów sesji będzie obsługiwać przenoszenie odtwarzania.

Zachowywanie stanu sesji

Pakiet SDK odbiornika internetowego udostępnia domyślną implementację aplikacji odbiornika internetowego, która umożliwia zachowanie stanów sesji przez utworzenie zrzutu bieżącego stanu multimediów, przekonwertowanie stanu na żądanie wczytania i wznowienie sesji z żądaniem wczytania.

W razie potrzeby żądanie wczytania wygenerowane przez odbiornik internetowy można zastąpić w przechwytywaczu komunikatów SESSION_STATE. Jeśli chcesz dodać do żądania wczytania dane niestandardowe, zalecamy umieszczenie ich w loadRequestData.customData.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.SESSION_STATE,
    function (sessionState) {
        // Override sessionState.loadRequestData if needed.
        const newCredentials = updateCredentials_(sessionState.loadRequestData.credentials);
        sessionState.loadRequestData.credentials = newCredentials;

        // Add custom data if needed.
        sessionState.loadRequestData.customData = {
            'membership': 'PREMIUM'
        };

        return sessionState;
    });

Dane niestandardowe można pobrać z loadRequestData.customData w interceptorze wiadomości RESUME_SESSION.

let cred_ = null;
let membership_ = null;

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.RESUME_SESSION,
    function (resumeSessionRequest) {
        let sessionState = resumeSessionRequest.sessionState;

        // Modify sessionState.loadRequestData if needed.
        cred_ = sessionState.loadRequestData.credentials;

        // Retrieve custom data.
        membership_ = sessionState.loadRequestData.customData.membership;

        return resumeSessionRequest;
    });

Wstępne wczytywanie treści

Odbiornik internetowy obsługuje wstępne wczytywanie elementów multimedialnych po bieżącym elemencie odtwarzania w kolejce.

Operacja wstępnego wczytywania powoduje pobranie kilku segmentów nadchodzących elementów. Specyfikacja jest wykonywana na wartości preloadTime w obiekcie QueueItem (jeśli nie zostanie podana, domyślnie jest to 20 sekund). Czas jest wyrażony w sekundach względem końca aktualnie odtwarzanego elementu . Dozwolone są tylko wartości dodatnie. Jeśli na przykład wartość wynosi 10 sekund, ten element zostanie wstępnie załadowany na 10 sekund przed zakończeniem poprzedniego elementu. Jeśli czas do wstępnego wczytania jest dłuższy niż czas pozostały do zakończenia bieżącego elementu, wstępne wczytanie nastąpi tak szybko, jak to możliwe. Jeśli więc w queueItem zostanie określona bardzo duża wartość wstępnego wczytywania, można uzyskać efekt, w którym podczas odtwarzania bieżącego elementu wstępnie wczytywany jest już następny element. Pozostawiamy jednak ustawienie i wybór tej opcji deweloperowi, ponieważ ta wartość może wpływać na przepustowość i wydajność strumieniowania aktualnie odtwarzanego elementu.

Wstępne wczytywanie będzie domyślnie działać w przypadku treści strumieniowych HLS, DASH i Smooth.

Zwykłe pliki wideo MP4 i pliki audio, takie jak MP3, nie będą wstępnie wczytywane, ponieważ urządzenia Cast obsługują tylko 1 element multimedialny i nie można ich używać do wstępnego wczytywania, gdy istniejący element treści jest nadal odtwarzany.

Komunikaty niestandardowe

Wymiana wiadomości to kluczowa metoda interakcji w przypadku aplikacji odbiornika internetowego.

Nadawca wysyła wiadomości do odbiornika internetowego za pomocą interfejsów API nadawcy na platformie, na której działa nadawca (Android, iOS, internet). Obiekt zdarzenia (który jest manifestacją wiadomości) przekazywany do detektorów zdarzeń ma element danych (event.data), w którym dane przyjmują właściwości określonego typu zdarzenia.

Aplikacja odbiornika internetowego może nasłuchiwać wiadomości w określonej przestrzeni nazw. Dzięki temu aplikacja odbiornika internetowego obsługuje protokół tej przestrzeni nazw. Następnie nadawcy, którzy chcą komunikować się w tej przestrzeni nazw, muszą użyć odpowiedniego protokołu.

Wszystkie przestrzenie nazw są definiowane przez ciąg znaków i muszą zaczynać się od „urn:x-cast:”, po którym następuje dowolny ciąg znaków. np. „urn:x-cast:com.example.cast.mynamespace”.

Uwaga: przestrzeń nazw wiadomości multimedialnych „urn:x-cast:com.google.cast.media” jest zarezerwowana. Wiadomości multimedialne wysyłane za pomocą interfejsów Cast API zarówno po stronie nadawcy, jak i odbiornika internetowego, zgodnie z konwencją używają protokołu przestrzeni nazw multimediów. Więcej informacji o wiadomościach multimedialnych znajdziesz w artykule Multimedia i odtwarzacze.

Oto fragment kodu, który umożliwia odbiornikowi internetowemu nasłuchiwanie niestandardowych komunikatów od połączonych nadawców:

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

const CUSTOM_CHANNEL = 'urn:x-cast:com.example.cast.mynamespace';
context.addCustomMessageListener(CUSTOM_CHANNEL, function(customEvent) {
  // handle customEvent.
});

context.start();

Podobnie aplikacje odbiornika internetowego mogą informować nadawców o stanie odbiornika internetowego, wysyłając wiadomości do połączonych nadawców. Aplikacja odbiornika internetowego może wysyłać wiadomości za pomocą sendCustomMessage(namespace, senderId, message) w CastReceiverContext. Odbiornik internetowy może wysyłać wiadomości do pojedynczego nadawcy w odpowiedzi na otrzymaną wiadomość lub z powodu zmiany stanu aplikacji. Oprócz przesyłania wiadomości typu punkt-punkt (z limitem 64 KB) odbiornik internetowy może też wysyłać komunikaty do wszystkich połączonych nadawców.

Urządzenia audio z Cast

Aby dowiedzieć się, jak odtwarzać sam dźwięk, zapoznaj się z przewodnikiem po Google Cast na urządzeniach audio.

Android TV

W tej sekcji opisujemy, jak odbiornik internetowy Google wykorzystuje dane wejściowe jako odtwarzanie i zgodność z Androidem TV.

Integracja aplikacji z pilotem

Odbiornik internetowy Google działający na urządzeniu z Androidem TV tłumaczy dane wejściowe z urządzeń sterujących (np. pilota) na komunikaty odtwarzania multimediów zdefiniowane dla przestrzeni nazw urn:x-cast:com.google.cast.media, zgodnie z opisem w sekcji Komunikaty odtwarzania multimediów. Aplikacja musi obsługiwać te komunikaty, aby sterować odtwarzaniem multimediów i umożliwić podstawowe sterowanie odtwarzaniem za pomocą elementów sterujących odtwarzaniem Androida TV.

Wskazówki dotyczące zgodności z Androidem TV

Oto kilka zaleceń i typowych błędów, których należy unikać, aby aplikacja była zgodna z Androidem TV:

• Pamiętaj, że ciąg znaków klienta użytkownika zawiera zarówno „Android”, jak i „CrKey”. Niektóre witryny mogą przekierowywać do witryny przeznaczonej tylko na urządzenia mobilne, ponieważ wykrywają etykietę „Android”. Nie zakładaj, że „Android” w ciągu znaków klienta użytkownika zawsze oznacza użytkownika mobilnego.
• Stos multimediów Androida może używać przezroczystego GZIP do pobierania danych. Upewnij się, że dane multimedialne mogą odpowiadać na zapytania Accept-Encoding: gzip.
• Zdarzenia multimedialne HTML5 na Androidzie TV mogą być wywoływane w innym czasie niż na Chromecaście, co może ujawnić problemy, które były ukryte na Chromecaście.
• Podczas aktualizowania multimediów używaj zdarzeń związanych z multimediami, które są wywoływane przez elementy <audio>/<video>, takie jak timeupdate, pause i waiting. Unikaj używania zdarzeń związanych z siecią, takich jak progress, suspend i stalled, ponieważ zwykle zależą one od platformy. Więcej informacji o obsłudze zdarzeń multimedialnych w odbiorniku znajdziesz w artykule o zdarzeniach multimedialnych.
• Podczas konfigurowania certyfikatów HTTPS witryny odbiorcy pamiętaj o uwzględnieniu pośrednich certyfikatów CA. Odwiedź stronę testową Qualsys SSL, aby sprawdzić, czy zaufana ścieżka certyfikacji Twojej witryny zawiera certyfikat CA oznaczony jako „extra download” (dodatkowe pobieranie). Jeśli tak, może on nie ładować się na platformach opartych na Androidzie.
• Chromecast wyświetla stronę odbiornika w rozdzielczości 720p, ale inne platformy Cast, w tym Android TV, mogą wyświetlać ją w rozdzielczości do 1080p. Upewnij się, że strona odbiornika skaluje się prawidłowo w różnych rozdzielczościach.