Como depurar apps receptores de transmissão

1. Visão geral

Logotipo do Google Cast

Este codelab vai ensinar você a adicionar o Cast Debug Logger ao seu app receptor da Web personalizado.

O que é o Google Cast?

O SDK do Google Cast permite que seu app reproduza conteúdo e controle a reprodução em dispositivos compatíveis com o Google Cast. Ele fornece os componentes de interface necessários de acordo com a Checklist de design do Google Cast.

Essa lista é fornecida para facilitar a experiência do usuário do Google Cast e deixá-la mais previsível em todas as plataformas compatíveis.

O que vamos criar?

Ao concluir este codelab, você terá um receptor da Web personalizado integrado ao registrador de depuração do Cast.

Consulte o guia do depurador de registros do Cast para mais detalhes e informações.

O que você vai aprender

Como configurar seu ambiente para desenvolvimento do Web Receiver.
Como integrar o Debug Logger ao seu receptor do Cast.

O que é necessário

A versão mais recente do navegador Google Chrome.
Serviço de hospedagem HTTPS, como o Firebase Hosting ou o ngrok.
Um dispositivo de transmissão, como um Chromecast ou Android TV, configurado com acesso à Internet.
Uma TV ou um monitor com entrada HDMI.

Experiência

Você precisa ter experiência anterior com o Cast e entender como funciona um Web Receiver do Cast.
Você precisa ter conhecimento prévio em desenvolvimento para a Web.
Também é necessário ter conhecimento prévio de como assistir TV :)

Como você usará este tutorial?

Apenas leitura

Leitura e exercícios

Como você classificaria sua experiência com a criação de apps da Web?

Iniciante

Intermediário

Proficiente

Como você classificaria sua experiência com o ato de assistir TV?

Iniciante

Intermediário

Proficiente

2. Acessar o exemplo de código

Você pode fazer download de todo o exemplo de código para seu computador…

e descompactar o arquivo ZIP salvo.

3. Implantar o receptor localmente

Para poder usar seu receptor da Web com um dispositivo de transmissão, ele precisa estar hospedado em algum lugar que o dispositivo possa acessar. Se você já tem um servidor compatível com HTTPS disponível, pule as instruções a seguir e anote o URL, porque ele será necessário na próxima seção.

Se você não tiver um servidor disponível para uso, use o Firebase Hosting ou o ngrok.

Executar o servidor

Depois de configurar o serviço escolhido, navegue até app-start e inicie o servidor.

Anote o URL do seu receptor hospedado. Você vai usá-lo na próxima seção.

4. Registrar um aplicativo no Play Console do Google Cast

É necessário registrar seu aplicativo para poder executar um Web Receiver personalizado nos dispositivos Chromecast, como o que criaremos neste codelab. Depois de registrar o aplicativo, você vai receber um ID do aplicativo que precisa ser usado pelo app remetente para fazer chamadas de API, como para iniciar um app receptor.

Imagem do Play Console do Cast com o botão "Adicionar novo aplicativo" em destaque

Clique em "Adicionar novo aplicativo".

Imagem da tela "Novo aplicativo receptor" com a opção "Receptor personalizado" destacada

Selecione "Custom Receiver", que é o que estamos criando.

Imagem do campo "URL do aplicativo receptor" na caixa de diálogo "Novo receptor personalizado" sendo preenchido

Insira os detalhes do novo receptor usando o URL da última seção. Anote o ID do aplicativo atribuído ao seu novo receptor.

Você também precisa registrar seu dispositivo de transmissão para que ele possa acessar o aplicativo receptor antes de você publicá-lo. Após a publicação, o aplicativo ficará disponível para todos os dispositivos com Google Cast. Para os fins deste codelab, é recomendável trabalhar com um aplicativo receptor não publicado.

Imagem do Google Cast SDK Play Console com o botão "Adicionar novo dispositivo" destacado

Clique em "Add new Device".

Imagem da caixa de diálogo "Adicionar dispositivo receptor de transmissão"

Insira o número de série impresso na parte de trás do seu dispositivo de transmissão e dê um nome descritivo para ele. Também é possível encontrar o número de série pela transmissão de tela no Chrome ao acessar o Play Console do SDK do Google Cast.

Levará de 5 a 15 minutos para que o receptor e o dispositivo estejam prontos para o teste. Após esse período, reinicie o dispositivo de transmissão.

5. Executar o app de amostra

Logotipo do Google Chrome

Enquanto aguardamos o novo Web Receiver ficar pronto para o teste, vamos ver um exemplo desse aplicativo concluído. O receptor que criaremos será capaz de reproduzir mídia por streaming com taxa de bits adaptável.

No navegador, abra a ferramenta CaC (link em inglês).

Imagem da guia "Controles de conexão e gravador do Cast" da ferramenta de comando e controle (CaC)

Use o ID do receptor padrão CC1AD845 e clique no botão SET APP ID.
Clique no botão Transmitir no canto superior esquerdo e selecione o dispositivo compatível com Google Cast.

Imagem da guia "Controles de conexão e registrador do Cast" da ferramenta de comando e controle (CaC) indicando que ela está conectada a um app receptor

Navegue até a guia LOAD MEDIA na parte de cima.

Imagem da guia "Carregar mídia" da ferramenta de comando e controle (CaC).

Mude o botão de opção do tipo de solicitação para LOAD.
Clique no botão SEND REQUEST para reproduzir um vídeo de amostra.
O vídeo será aberto no dispositivo compatível com Google Cast para mostrar qual é a aparência da funcionalidade básica usando o receptor padrão.

6. Preparar o projeto inicial

Precisamos adicionar compatibilidade com o Google Cast ao app inicial que você transferiu por download. Aqui está parte da terminologia do Google Cast que será usada neste codelab:

Um app remetente é executado em um dispositivo móvel ou laptop.
Um app receptor é executado no dispositivo com Google Cast ou dispositivo Android TV.

Agora você já pode criar com base no projeto inicial usando seu editor de texto favorito:

Selecione o diretório app-start no download do exemplo de código.
Abra js/receiver.js e index.html.

Enquanto você trabalha neste codelab, o http-server precisa detectar as mudanças feitas. Se não aparecer, tente parar e reiniciar o http-server.

Design de apps

O app receptor inicializa a sessão de transmissão e fica em espera até receber uma solicitação LOAD de um remetente, ou seja, o comando para iniciar uma mídia.

O app consiste em uma visualização principal, definida em index.html, e um arquivo JavaScript chamado js/receiver.js, contendo toda a lógica necessária para fazer nosso receptor funcionar.

index.html

Esse arquivo HTML contém toda a interface do usuário do nosso app receptor.

receiver.js

Esse script gerencia toda a lógica do nosso app receptor.

Perguntas frequentes

7. Integrar com a API CastDebugLogger

O SDK do receptor do Google Cast oferece outra opção para os desenvolvedores depurarem facilmente o app receptor usando a API CastDebugLogger.

Consulte o guia do depurador de registros do Cast para mais detalhes e informações.

Inicialização

Inclua o seguinte script na tag <head> do app receptor logo após o script do SDK Web Receiver, em index.html:

<head>
  ...
  <script src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <!-- Cast Debug Logger -->
  <script src="//www.gstatic.com/cast/sdk/libs/devtools/debug_layer/caf_receiver_logger.js"></script>
</head>

No js/receiver.js, na parte de cima do arquivo e abaixo do playerManager, receba a instância CastDebugLogger e ative o agente de registro em um listener de eventos READY:

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

// Debug Logger
const castDebugLogger = cast.debug.CastDebugLogger.getInstance();
const LOG_TAG = 'MyAPP.LOG';

// Enable debug logger and show a 'DEBUG MODE' overlay at top left corner.
context.addEventListener(cast.framework.system.EventType.READY, () => {
  if (!castDebugLogger.debugOverlayElement_) {
      castDebugLogger.setEnabled(true);
  }
});

Quando o agente de registro de depuração está ativado, uma sobreposição de DEBUG MODE é mostrada no receptor.

Imagem de um vídeo sendo reproduzido com a mensagem "DEBUG MODE" (MODO DE DEPURAÇÃO) em um fundo vermelho no canto superior esquerdo do frame

Registrar eventos do player

Com a CastDebugLogger, é possível registrar facilmente os eventos do player que são acionados pelo SDK do receptor da Web do Cast e usar diferentes níveis de registrador para registrar os dados de eventos. A configuração loggerLevelByEvents usa cast.framework.events.EventType e cast.framework.events.category para especificar os eventos a serem registrados.

Adicione o seguinte abaixo do listener de eventos READY para registrar quando os eventos CORE do player forem acionados ou uma mudança de mediaStatus for transmitida:

...

// Set verbosity level for Core events.
castDebugLogger.loggerLevelByEvents = {
  'cast.framework.events.category.CORE': cast.framework.LoggerLevel.INFO,
  'cast.framework.events.EventType.MEDIA_STATUS': cast.framework.LoggerLevel.DEBUG
};

Mensagens de registro e tags personalizadas

A API CastDebugLogger permite criar mensagens de registro que aparecem na sobreposição de depuração do receptor com cores diferentes. Use os seguintes métodos de registro, listados em ordem decrescente de prioridade:

castDebugLogger.error(custom_tag, message);
castDebugLogger.warn(custom_tag, message);
castDebugLogger.info(custom_tag, message);
castDebugLogger.debug(custom_tag, message);

Para cada método de registro, o primeiro parâmetro precisa ser uma tag personalizada e o segundo, a mensagem de registro. A tag pode ser qualquer string que você ache útil.

Para mostrar os registros em ação, adicione-os ao interceptador LOAD.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.LOAD,
      loadRequestData => {
    // Listed in order from highest to lowest priority.
    castDebugLogger.error(LOG_TAG, 'Test error log');

    castDebugLogger.warn(LOG_TAG, 'Test warn log');

    castDebugLogger.info(LOG_TAG, 'Intercepting LOAD request', loadRequestData);

    castDebugLogger.debug(LOG_TAG, 'Test debug log');

    return loadRequestData;
  }
);

Você pode controlar quais mensagens aparecem na sobreposição de depuração configurando o nível de registro em loggerLevelByTags para cada tag personalizada. Por exemplo, ativar uma tag personalizada com o nível de registro cast.framework.LoggerLevel.DEBUG exibirá todas as mensagens adicionadas com erro, aviso, informações e mensagens de registros de depuração. Outro exemplo é que ativar uma tag personalizada com o nível WARNING exibirá apenas mensagens de registro de erro e de aviso.

A configuração loggerLevelByTags é opcional. Se uma tag personalizada não for configurada para o nível do agente de registro, todas as mensagens de registro serão exibidas na sobreposição de depuração.

Adicione o seguinte abaixo da chamada loggerLevelByEvents:

...

// Set verbosity level for custom tags.
castDebugLogger.loggerLevelByTags = {
    LOG_TAG: cast.framework.LoggerLevel.DEBUG, // display all levels
};

...

8. Como usar a sobreposição de depuração

A API CastDebugLogger fornece uma sobreposição de depuração no receptor para mostrar as mensagens de registro personalizadas. Use showDebugLogs para alternar a sobreposição de depuração e clearDebugLogs para limpar as mensagens de registro nela.

Adicione o seguinte ao listener de eventos READY para visualizar a sobreposição de depuração no seu receptor:

// Enable debug logger and show a 'DEBUG MODE' overlay at top left corner.
context.addEventListener(cast.framework.system.EventType.READY, () => {
  if (!castDebugLogger.debugOverlayElement_) {
      castDebugLogger.setEnabled(true);

      // Show debug overlay.
      castDebugLogger.showDebugLogs(true);

      // Clear log messages on debug overlay.
      castDebugLogger.clearDebugLogs();
  }
});

Imagem mostrando a sobreposição de depuração, uma lista de mensagens de registro de depuração em um plano de fundo translúcido sobre um frame de vídeo

9. Como usar a ferramenta de comando e controle (CaC)

Visão geral

A ferramenta CaC captura seus registros e controla a sobreposição de depuração.

Há duas maneiras de conectar o receptor à ferramenta CaC:

Iniciar uma nova conexão do Cast:

Abra a ferramenta CaC, defina o ID do app receptor e clique no botão Transmitir para transmitir para o receptor.
Transmita um app remetente separado para o mesmo dispositivo com o mesmo ID do app receptor.
Carregue a mídia do app remetente. As mensagens de registro vão aparecer na ferramenta.

Participar de uma sessão do Cast:

Receba o ID da sessão do Google Cast em execução usando o SDK do receptor ou do remetente. No lado do receptor, digite o seguinte para receber o ID da sessão no console do Depurador remoto do Chrome:

cast.framework.CastReceiverContext.getInstance().getApplicationData().sessionId;

Ou você pode extrair o ID da sessão de um remetente da Web conectado usando o seguinte método:

cast.framework.CastContext.getInstance().getCurrentSession().getSessionId();

Imagem da guia "Controles de conexão e gravador do Cast" da ferramenta de comando e controle (CaC) para retomar a sessão

Insira o ID da sessão na ferramenta CaC e clique no botão RESUME.
O botão Transmitir precisa estar conectado e começar a mostrar mensagens de registro na ferramenta.

O que você pode tentar

Em seguida, vamos usar a ferramenta CaC para ver os registros no receptor de amostra.

Abra a ferramenta CaC.

Imagem da guia "Controles de conexão e gravador do Cast" da ferramenta de comando e controle (CaC)

Insira o ID do app receptor do seu app de exemplo e clique no botão SET APP ID.
Clique no botão Transmitir no canto superior esquerdo e selecione o dispositivo compatível com Google Cast para abrir o receptor.

Imagem da guia "Controles de conexão e registrador do Cast" da ferramenta de comando e controle (CaC) indicando que ela está conectada a um app receptor

Navegue até a guia LOAD MEDIA na parte de cima.

Imagem da guia "Carregar mídia" da ferramenta de comando e controle (CaC).

Mude o botão de opção do tipo de solicitação para LOAD.
Clique no botão SEND REQUEST para reproduzir um vídeo de amostra.

Imagem da guia "Controles de conexão e gravador do Cast" da ferramenta de comando e controle (CaC) com mensagens de registro preenchendo o painel inferior

Um vídeo de amostra vai começar a ser reproduzido no seu dispositivo. Os registros das etapas anteriores vão começar a aparecer na guia "Mensagens de registro", na parte de baixo da ferramenta.

Confira os seguintes recursos para investigar registros e controlar o receptor:

Clique na guia MEDIA INFO ou MEDIA STATUS para conferir as informações e o status da mídia.
Clique no botão SHOW OVERLAY para ver uma sobreposição de depuração no receptor.
Use o botão CLEAR CACHE AND STOP para recarregar o app receptor e transmitir novamente.

10. Parabéns

Agora você já sabe como adicionar o gravador de depuração do Cast ao seu app Web Receiver compatível com Cast usando o SDK do receptor do Cast mais recente.

Para mais detalhes, consulte os guias para desenvolvedores do Cast Debug Logger e da ferramenta de comando e controle (CaC).

Como depurar apps receptores de transmissão Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

1. Visão geral

O que é o Google Cast?

O que vamos criar?

O que você vai aprender

O que é necessário

Experiência

Como você usará este tutorial?

Como você classificaria sua experiência com a criação de apps da Web?

Como você classificaria sua experiência com o ato de assistir TV?

2. Acessar o exemplo de código

3. Implantar o receptor localmente

Executar o servidor

4. Registrar um aplicativo no Play Console do Google Cast

5. Executar o app de amostra

6. Preparar o projeto inicial

Design de apps

index.html

receiver.js

Perguntas frequentes

7. Integrar com a API CastDebugLogger

Inicialização

Registrar eventos do player

Mensagens de registro e tags personalizadas

8. Como usar a sobreposição de depuração

9. Como usar a ferramenta de comando e controle (CaC)

Visão geral

O que você pode tentar

10. Parabéns

Como depurar apps receptores de transmissão