Migrar para o receptor da Web

Este guia explica como migrar um app receptor de Cast v2 para o app receptor da Web mais recente.

O novo SDK do Cast Application Framework (CAF), também conhecido como Web Receiver v3, é um upgrade importante do SDK do Receiver v2. O SDK do receptor da Web fornece um SDK fácil e simplificado para desenvolver aplicativos de receptor da Web de mídia.

O receptor da Web fornece uma API mais consistente com as novas APIs de remetente do CAF. Ele oferece integração total de um jogador (MPL e Shaka), além de implementação e suporte completos para mídia do Google Cast e comandos de voz do Google Assistente. O SDK do CAF também fornece uma IU padrão que pode ser facilmente estilizado com CSS e um serviço de vinculação de dados para simplificar a implementação da IU.

Por que migrar?

Ao migrar um aplicativo receptor v2 para o receptor da Web, muito código pode ser eliminado. Assim, você pode se concentrar em escrever a lógica de negócios específica do aplicativo.

O CAF integra perfeitamente os players MPL e Shaka para oferecer suporte a uma maior variedade de tipos de conteúdo, incluindo HTTP Live Streaming (TS e CMAF), MPEG-DASH, Smooth Streaming e tipos compatíveis com a propriedade de origem Media Element (MP3, MP4, Icecast etc.). Para ver uma lista completa, consulte Mídias compatíveis com o Google Cast. No momento, o CAF não oferece suporte a um player fornecido pelo usuário.

A migração para o CAF adicionará o suporte ao controle de voz com o Google Assistente. Qualquer novo comando de voz do Google Assistente vai ser compatível automaticamente com o CAF.

Além de oferecer compatibilidade com novos comandos de mídia, como "faixas alteradas por idioma" e "taxa de reprodução de alteração", o CAF também fornece filas melhores, suporte integrado a anúncios e melhor suporte em tempo real.

O que mudou?

A API Web Receiver tenta seguir as convenções que foram introduzidas pelos remetentes do CAF para Android e iOS e é bem diferente da v2.

O receptor da Web está usando um novo namespace cast.framework em vez de cast.receiver para todas as APIs expostas. Muitos dos objetos de dados usados pela v2 são os mesmos no CAF e são expostos no namespace cast.framework.messages (geralmente em cast.receiver.media).

Os seguintes serviços da v2 foram substituídos pelos serviços do CAF correspondentes:

  • A classe CastReceiverManager foi substituída por CastReceiverContext, que é um Singleton que gerencia a sessão de transmissão, os remetentes, o envio de mensagens personalizadas e os eventos globais do sistema. O CastReceiverOptions pode ser usado para fornecer opções globais de aplicativos (como fila, versão do receptor, configuração de reprodução etc.) ao contexto.
  • A classe MediaManager foi substituída pela PlayerManager, que é uma propriedade do singleton CastReceiverContext, e gerencia a sessão de mídia, as solicitações de mídia e as solicitações de voz do Google Assistente (CommandAndControlManager na v2) e dispara eventos de mídia. A configuração dos jogadores (cast.player.api.Host no MPL) é fornecida por PlaybackConfig, que pode ser fornecida globalmente ou por solicitação de carregamento.

O PlayerManager também expõe as novas classes de subadministrador:

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);

Lógica de negócios do destinatário

Gerenciadores de eventos expostos do receptor v2 (como CastReceiverManager.onReady ou MediaManager.onLoad) para adicionar lógica de negócios. No CAF, os manipuladores de eventos são substituídos por listeners de eventos (CastReceiverContext.addEventListener) e interceptadores de mensagens (PlayerManager.setMessageInterceptor). O receptor da Web pode ter vários listeners de eventos para um evento (o listener não afeta o evento) e um interceptador por mensagem. Ele pode atualizar ou processar a solicitação (retornar uma solicitação modificada, uma mensagem de sucesso ou uma mensagem de erro) e ser um gerenciador assíncrono que retorna uma promessa.

O interceptador da solicitação de carregamento é o lugar mais comum para adicionar lógica específica do aplicativo. Para solicitações de carregamento de um remetente, o interceptor pode carregar o ID do conteúdo em um URL de conteúdo. O interceptador de carregamento também será chamado para solicitações de pré-carregamento e pré-cache se nenhum interceptor explícito for fornecido para pré-carregamento ou pré-cache.

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;
    });

O gerenciador de status de mídia personalizado da v2 também foi substituído por um interceptador para a mensagem de status de mídia. Apps do receptor da Web que não querem expor o URL de mídia no status podem fornecer um resolvedor de URL (PlayerManager.setMediaUrlResolver), que fornece o URL para uma solicitação de carregamento. Esse URL é usado internamente pelo CAF e não é fornecido no status da mídia.

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

Eventos

O Web Receiver fornece um conjunto abrangente de eventos de CastReceiverContext e PlayerManager. Os apps Web Receiver podem ter vários listeners em qualquer evento e também podem fornecer um listener a vários eventos. Consulte cast.framework.events.category para ver alguns grupos de eventos.

Os eventos abrangem qualquer solicitação do usuário, progresso da reprodução, processamento do jogador e qualquer evento de elemento de mídia de baixo nível (o CAF não expõe o próprio elemento de mídia).

O app Web Receiver pode adicionar listeners de eventos para realizar ações (por exemplo, adicionar definição de faixas de texto quando a carga for concluída) ou para análise.

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

Barramento de mensagens personalizado

O CAF não expõe o barramento de mensagens na API. Em vez disso, ele fornece CastReceiverContext.addCustomMessageListener para adicionar um listener de mensagens a um namespace específico (apenas um por namespace) e CastReceiverContext.sendCustomMessage para enviar uma mensagem em um namespace. Todos os namespaces precisam ser declarados antes de iniciar o receptor da Web (ou seja, antes de chamar CastReceiverContext.start). Os namespaces podem ser declarados adicionando um listener de mensagens a eles ou podem ser fornecidos como uma opção inicial em 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'
});

IU padrão

O CAF fornece uma IU padrão do receptor da Web que exibe uma barra de progresso da reprodução e metadados de mídia conforme necessário. A IU padrão é fornecida como um elemento personalizado (<cast-media-player>) que pode ser estilizado com estilo semelhante a CSS.

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

Para personalizar ainda mais, um app Web Receiver pode implementar a própria IU. O Web Receiver fornece a classe cast.framework.ui.PlayerDataBinder para ajudar a vincular um objeto de IU ao estado de reprodução do Web Receiver.