Migrar para o receptor da Web

Este guia explica como migrar um app Cast Receiver v2 para a versão mais recente App receptor.

O novo SDK do Cast Application Framework (CAF), também conhecido como Web Receiver v3, está um upgrade importante em relação ao SDK do Receiver v2. O SDK do receptor da Web oferece uma SDK fácil e simplificado para desenvolver aplicativos receptores da web de mídia.

O receptor da Web fornece uma API mais consistente com o novo remetente do CAF APIs de terceiros. Ele fornece integração total de um player (MPL e Shaka) e implementação e compatibilidade com a mídia do Google Cast e o Google Assistente comandos de voz. O SDK do CAF também fornece uma interface padrão que pode ser estilizada facilmente CSS e um serviço de vinculação de dados para simplificar a implementação da interface.

Por que migrar?

Ao migrar um aplicativo Receiver v2 para Web Receiver, muitos códigos que lidam com o jogador pode ser eliminado, para que você possa se concentrar em escrever lógica de negócios específica do aplicativo.

O CAF integra perfeitamente players MPL e Shaka para oferecer suporte a uma gama mais ampla 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 do elemento de mídia (MP3, MP4, Icecast etc.). Para acessar uma lista completa, consulte Mídias compatíveis com o Google Cast. No momento, o CAF não é compatível com um player fornecido pelo usuário.

A migração para o CAF adicionará a compatibilidade com o controle de voz com o Google Assistente. Qualquer novo comando de voz do Google Assistente será compatível automaticamente quando usando o CAF.

Além de oferecer suporte a novos comandos de mídia, como "mudar faixas por idioma" e “alterar a velocidade do vídeo” — o CAF também oferece melhor enfileiramento, anúncios integrados e um suporte melhor em tempo real.

O que mudou?

A API Web Receiver tenta seguir as convenções introduzidas pelos Remetentes de CAF para Android e iOS, e é bem diferente da v2.

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

Os seguintes serviços da v2 foram substituídos pelos serviços 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 mensagens e eventos do sistema global. A CastReceiverOptions pode ser usado para fornecer opções de aplicativos globais (como filas, versão, configuração de reprodução etc.) ao contexto.
  • A classe MediaManager foi substituída por PlayerManager que é uma propriedade do CastReceiverContext Singleton e gerencia a sessão de mídia, as solicitações de mídia, os Solicitações de voz do Assistente (CommandAndControlManager na v2), e dispara eventos de mídia. Configuração para os jogadores (cast.player.api.Host em MPL) é fornecido por PlaybackConfig, que podem ser fornecidos 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 receptor

Manipuladores 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 diversos listeners de eventos para um evento (o listener não afeta o evento), e um interceptador por mensagem. O interceptador pode atualizar ou processar a solicitação (retornar uma solicitação modificada, uma solicitação ou mensagem de erro) e podem ser um gerenciador assíncrono que retorna uma promessa.

O interceptador de solicitação de carregamento é o local mais comum para adicionar lógica específica do aplicativo. Para solicitações de carregamento de um remetente, interceptador pode converter o ID de conteúdo em um URL de conteúdo. O interceptador de carga é também está sendo chamado para solicitações de pré-carregamento e pré-cache se nenhum interceptador explícito foi 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 v2 também é substituído por uma mensagem para a mensagem de status da mídia. Os apps receptores da Web que não quiserem Expor o URL de mídia no status da mídia pode fornecer um resolvedor de URL (PlayerManager.setMediaUrlResolver), que fornece o URL de mídia para uma solicitação de carregamento. Esse URL é usado pelo CAF internamente 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 receptor da Web oferece um conjunto extenso de eventos, de CastReceiverContext e PlayerManager Os aplicativos receptores da Web podem ter vários listeners em qualquer evento, e também pode fornecer um listener para vários eventos. Consulte cast.framework.events.category para alguns grupos de eventos.

Os eventos abrangem qualquer solicitação do usuário, progresso da reprodução, processamento do player 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 ações (por exemplo, adicionar texto rastreia a definição quando o carregamento é concluído) 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, fornece CastReceiverContext.addCustomMessageListener para adicionar um listener de mensagens para 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 iniciando o receptor da Web (ou seja, antes de chamar CastReceiverContext.start). Os namespaces podem ser declarados pelo adicionando um listener de mensagem a eles ou pode ser fornecido como uma opção de início 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'
});

interface padrão

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

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

Para mais personalização, um app receptor da Web pode implementar a própria interface. A O receptor da Web fornece cast.framework.ui.PlayerDataBinder para ajudar a vincular um objeto de interface ao estado de reprodução do receptor da Web.