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 porCastReceiverContext
, que é um Singleton que gerencia a sessão de transmissão, os remetentes, o envio de mensagens personalizadas e os eventos globais do sistema. OCastReceiverOptions
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 pelaPlayerManager
, que é uma propriedade do singletonCastReceiverContext
, 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 porPlaybackConfig
, que pode ser fornecida globalmente ou por solicitação de carregamento.
O PlayerManager
também expõe as novas classes de subadministrador:
TextTracksManager
: gerencia as faixas de texto de mídia.AudioTracksManager
: gerencia as faixas de áudio.QueueManager
: gerencie a fila.BreakManager
: gerencia anúncios.
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.