Adicionar principais recursos ao seu receptor da Web personalizado

Esta página contém snippets de código e descrições dos recursos disponíveis para um app receptor da Web personalizado.

Observação:recomendamos que você faça o seguinte:

• Tutorial do codelab sobre receptor da Web do Google Cast: aprenda passo a passo como criar um app receptor da Web compatível com Cast usando o SDK do Google Cast que pode receber transmissões de vídeo.
• App de exemplo CastReceiver (GitHub): execute, navegue e visualize este app de amostra de referência que está em conformidade com as Diretrizes de UX e a Lista de verificação de design.

1. Um elemento cast-media-player que representa a IU do player integrada fornecida com o Web Receiver.
2. Estilo personalizado semelhante ao CSS do elemento cast-media-player para estilizar vários elementos da IU, como background-image, splash-image e font-family.
3. Um elemento de script para carregar a estrutura do Web Receiver.
4. Código JavaScript para interceptar mensagens e manipular eventos.
5. Fila para reprodução automática.
6. Opções para configurar a reprodução.
7. Opções para definir o contexto do Web Receiver.
8. Opções para definir comandos compatíveis com o app Web Receiver.
9. Uma chamada JavaScript para iniciar o aplicativo Web Receiver.

Observação: é altamente recomendável usar o elemento HTML cast-media-player, já que ele processa todo o estado da IU do player junto com o estilo.

Configuração e opções do aplicativo

A CastReceiverContext é a classe mais externa exposta ao desenvolvedor e gerencia o carregamento de bibliotecas subjacentes e processa a inicialização do SDK do Web Receiver.

Se a API Web Receiver detectar que um remetente está desconectado, ele acionará o evento SENDER_DISCONNECTED. Se o Web Receiver não conseguir se comunicar com o remetente pelo que descrevemos como maxInactivity segundos, ele também acionará o evento SENDER_DISCONNECTED. Durante o desenvolvimento, é recomendável definir maxInactivity como um valor alto para que o app Web Receiver não feche ao depurar o app com o Chrome Remote Debugger:

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

No entanto, para um aplicativo de receptor da Web publicado, é melhor não definir maxInactivity e depender do valor padrão. Observe que as opções do Web Receiver são definidas apenas uma vez no aplicativo.

A outra configuração é a cast.framework.PlaybackConfig. Isso pode ser definido da seguinte maneira:

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

Essa configuração afeta cada reprodução de conteúdo e fornece essencialmente comportamento de modificação. Para ver uma lista de comportamentos que os desenvolvedores podem modificar, consulte a definição de cast.framework.PlaybackConfig. Para alterar a configuração entre conteúdos, é possível usar o PlayerManager para acessar o playbackConfig atual, modificar ou adicionar uma substituição e redefinir o playbackConfig desta forma:

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

Se PlaybackConfig não tiver sido modificado, getPlaybackConfig() retornará um objeto nulo. E qualquer propriedade em PlaybackConfig that será undefined usará os valores padrão.

Listener de eventos

O SDK do Web Receiver permite que seu app Web Receiver gerencie os eventos do player. O listener de eventos usa um parâmetro cast.framework.events.EventType (ou uma matriz desses parâmetros) que especifica os eventos que devem acionar o listener. Matrizes pré-configuradas de cast.framework.events.EventType, que são úteis para depuração, podem ser encontradas em cast.framework.events.category. O parâmetro "event" fornece informações adicionais sobre o evento.

Por exemplo, se você quiser saber quando uma mudança de mediaStatus está sendo transmitida, use a seguinte lógica para processar o evento:

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

Observação: o framework do Web Receiver detecta automaticamente quando um remetente se conecta ou desconecta dele e não requer um listener de eventos SENDER_DISCONNECTED explícito na sua própria lógica do Web Receiver.

Interceptação de mensagens

O SDK do Web Receiver permite que seu app Web Receiver intercepte mensagens e execute códigos personalizados nessas mensagens. O interceptador de mensagens usa um parâmetro cast.framework.messages.MessageType que especifica o tipo de mensagem que precisa ser interceptada.

O interceptador precisa retornar a solicitação modificada ou uma promessa que seja resolvida com o valor da solicitação modificada. Retornar null impedirá que o gerenciador de mensagens padrão seja chamado. Consulte Como carregar mídia para mais detalhes.

Por exemplo, se você quiser alterar os dados da solicitação de carregamento, use a seguinte lógica para interceptá-los e modificá-los:

Cuidado: não adicione nem modifique a propriedade queueData do LoadRequestData no interceptador LOAD. Ela não terá efeito na reprodução, porque o queueData já foi lido e aplicado à fila. Para mais informações, consulte o guia de enfileiramento.

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

Tratamento de erros

Quando ocorrem erros no interceptador de mensagens, seu app Web Receiver precisa retornar um cast.framework.messages.ErrorType e um cast.framework.messages.ErrorReason adequados.

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

Interceptação de mensagens x listener de eventos

Estas são algumas das principais diferenças entre a interceptação de mensagens e o listener de eventos:

• Um listener de eventos não permite que você modifique os dados da solicitação.
• É melhor usar um listener de eventos para acionar análises ou uma função personalizada.

Observação: um listener de eventos também pode ser usado para detectar um conjunto de eventos usando a enumeração CORE, DEBUG ou FINE.

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

• A interceptação de mensagens permite que você ouça, intercepte e modifique os dados da solicitação em si.
• A interceptação de mensagens é melhor usada para lidar com a lógica personalizada em relação aos dados da solicitação.

Como carregar mídia

MediaInformation fornece várias propriedades para carregar mídia na mensagem cast.framework.messages.MessageType.LOAD, incluindo entity, contentUrl e contentId.

O entity é a propriedade sugerida a ser usada na implementação dos apps de recebimento e de recebimento. A propriedade é um URL de link direto que pode ser uma playlist ou um conteúdo de mídia específico.

O contentUrl foi criado para um URL reproduzível e pode ser usado depois que estiver disponível.

O uso do contentId foi suspenso devido à ambiguidade de se o valor é um URL da mídia, um ID real ou um parâmetro de chave para pesquisa personalizada.

A sugestão é usar entity para armazenar o ID real ou os parâmetros principais e usar contentUrl para o URL da mídia. Um exemplo disso é mostrado no snippet a seguir, em que entity está presente na solicitação LOAD e o contentUrl reproduzível é recuperado:

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

Recursos do dispositivo

O método getDeviceCapabilities fornece informações sobre o dispositivo de transmissão conectado e o dispositivo de vídeo ou áudio conectado a ele. O método getDeviceCapabilities fornece informações de suporte para o Google Assistente, o Bluetooth e os dispositivos de áudio e tela conectados.

Esse método retorna um objeto que pode ser consultado passando um dos enums especificados para receber a capacidade de dispositivo para esse enum. Os tipos enumerados são definidos em cast.framework.system.DeviceCapabilities.

Este exemplo verifica se o dispositivo receptor da Web é capaz de reproduzir HDR e DolbyVision (DV) com as chaves IS_HDR_SUPPORTED e IS_DV_SUPPORTED, respectivamente.

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

Como gerenciar a interação do usuário

O usuário pode interagir com o app Web Receiver por meio de aplicativos de envio (Web, Android e iOS), comandos de voz em dispositivos com Google Assistente, controles de toque em smart displays e controles remotos em dispositivos Android TV. O SDK do Cast fornece várias APIs para permitir que o app Web Receiver processe essas interações, atualize a IU do app por meio de estados de ação do usuário e, opcionalmente, envie as mudanças para atualizar os serviços de back-end.

Comandos de mídia compatíveis

Os estados dos controles de IU são impulsionados pelo MediaStatus.supportedMediaCommands para controladores expandidos do iOS e do Android, apps de controle remoto e receptores em execução em dispositivos touchscreen e apps receptores em dispositivos Android TV. Quando um Command bit a bit específico é ativado na propriedade, os botões relacionados a essa ação são ativados. Se o valor não for definido, o botão será desativado. Estes valores podem ser alterados no Web Receiver:

1. Uso de PlayerManager.setSupportedMediaCommands para definir o Commands específico
2. Como adicionar um novo comando usando addSupportedMediaCommands
3. Como remover um comando existente usando removeSupportedMediaCommands.

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

Quando o receptor prepara o MediaStatus atualizado, ele inclui as mudanças na propriedade supportedMediaCommands. Quando o status é transmitido, os apps de remetentes conectados atualizam os botões na IU de acordo.

Observação: fazer mudanças no supportedMediaCommands não mudará o tipo de botão exibido. Eles são definidos diretamente nos apps remetentes (iOS, Android) e na API Controls do destinatário. A única exceção que usa o supportedMediaCommands para realizar essas mudanças são os cards de reprodução de mídia na tela inicial dos dispositivos inteligentes.

Para mais informações sobre comandos de mídia compatíveis e dispositivos de toque, consulte o guia Accessing UI controls.

Como gerenciar estados de ação do usuário

Quando os usuários interagem com a IU ou enviam comandos de voz, eles podem controlar a reprodução do conteúdo e das propriedades relacionadas ao item em reprodução. As solicitações que controlam a reprodução são processadas automaticamente pelo SDK. As solicitações que modificam propriedades do item em reprodução, como um comando LIKE, exigem que o app receptor as processe. O SDK fornece uma série de APIs para lidar com esses tipos de solicitações. Para aceitar essas solicitações, é preciso fazer o seguinte:

• Intercepte USER_ACTION mensagens e determine a ação solicitada.
• Atualize o MediaInformation UserActionState para atualizar a IU.

Observação: se necessário, você pode POST a ação a back-ends relevantes para manter a preferência do usuário.

O snippet abaixo intercepta a mensagem USER_ACTION e processa a chamada do back-end com a alteração solicitada. Em seguida, ele faz uma chamada para atualizar o UserActionState no receptor.

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

O snippet abaixo simula uma chamada para um serviço de back-end. A função verifica o UserActionRequestData para ver o tipo de mudança solicitada pelo usuário e só faz uma chamada de rede se a ação for compatível com o back-end.

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

O snippet abaixo usa o UserActionRequestData e adiciona ou remove o UserActionState do MediaInformation. Atualizar o UserActionState do MediaInformation muda o estado do botão associado à ação solicitada. Essa mudança é refletida na IU dos controles de smart display, no app de controle remoto e na IU do Android TV. Ele também é transmitido por mensagens de saída MediaStatus para atualizar a IU do controlador expandido para remetentes do iOS e do Android.

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

Comandos de voz

No momento, os seguintes comandos de mídia são compatíveis com o SDK do receptor da Web para dispositivos com Google Assistente. As implementações padrão desses comandos são encontradas em cast.framework.PlayerManager.

Comando	Descrição
Tocar	Reproduz ou retoma a reprodução do estado pausado.
Pausar	Pausar conteúdo em reprodução no momento.
Anterior	Pule para o item de mídia anterior na fila.
Próxima	Pule para o próximo item de mídia na fila de mídia.
Parar	Interrompe a mídia em reprodução no momento.
Nenhum	Desative a repetição de itens de mídia na fila quando a última reprodução do item for concluída.
Repetir single	Repita a mídia que está sendo reproduzida indefinidamente.
Repetir tudo	Repita todos os itens da fila quando o último item da fila for reproduzido.
Repetir tudo e reproduzir aleatoriamente	Depois que a reprodução do último item da fila for concluída, reproduza a fila aleatoriamente e repita todos os itens na fila.
Embaralhar	Reproduzir itens de mídia aleatoriamente na fila de mídia. Observação:também é possível usar a sinalização shuffle para embaralhar a mídia antes da reprodução, se ela estiver definida no loadRequestData da mensagem LOAD.
Legendas ativadas / DESATIVADAS	Ativar / Desativar legendas ocultas para a sua mídia. A opção Ativar / Desativar também está disponível por idioma.
Procurar até o tempo absoluto	Pula para a hora absoluta especificada.
Procurar em relação ao tempo relativo ao horário atual	avança ou retrocede pelo período de tempo especificado em relação ao tempo de reprodução atual.
Jogar novamente	Reinicie a mídia em reprodução no momento ou reproduza o último item de mídia reproduzido se nada estiver sendo reproduzido.
Definir a taxa de reprodução	Varie a taxa de reprodução de mídia. Isso deve ser tratado por padrão. Você pode usar o interceptador de mensagens SET_PLAYBACK_RATE para modificar as solicitações de taxa de entrada.

Comandos de mídia compatíveis com voz

Para impedir que um comando de voz acione um comando de mídia em um dispositivo com Google Assistente, defina primeiro os comandos de mídia compatíveis que você planeja oferecer. Em seguida, ative esses comandos ativando a propriedade CastReceiverOptions.enforceSupportedCommands. A IU nos remetentes do SDK do Google Cast e dos dispositivos com função de toque será alterada para refletir essas configurações. Se a sinalização não estiver ativada, os comandos de entrada de voz serão executados.

Por exemplo, se você permitir PAUSE dos aplicativos remetentes e dispositivos com recurso de toque, também precisará configurar o receptor para refletir essas configurações. Quando configurados, os comandos de voz de entrada serão descartados se não forem incluídos na lista de comandos compatíveis.

No exemplo abaixo, fornecemos o CastReceiverOptions ao iniciar o CastReceiverContext. Adicionamos suporte ao comando PAUSE e aplicamos o player apenas a esse comando. Agora, se um comando de voz solicitar outra operação, como SEEK, ele será negado. O usuário será notificado de que o comando ainda não é compatível.

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

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

É possível aplicar uma lógica separada para cada comando que você quer restringir. Remova a sinalização enforceSupportedCommands e, para cada comando que você quer restringir, é possível interceptar a mensagem recebida. Aqui, interceptamos a solicitação fornecida pelo SDK para que os comandos SEEK emitidos para dispositivos com Google Assistente não acionem uma busca no aplicativo receptor da Web.

Para comandos de mídia não compatíveis com o aplicativo, retorne um motivo de erro apropriado, como 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;
  });

Segundo plano a partir da atividade de voz

Se a plataforma de transmissão estiver em segundo plano no som do aplicativo devido à atividade do Google Assistente, como ouvir a fala do usuário ou responder, uma mensagem FocusState de NOT_IN_FOCUS será enviada ao aplicativo receptor da Web quando a atividade for iniciada. Outra mensagem com IN_FOCUS é enviada quando a atividade termina. Dependendo do seu aplicativo e da mídia que está sendo reproduzida, pause a mídia quando FocusState for NOT_IN_FOCUS, interceptando o tipo de mensagem FOCUS_STATE.

Por exemplo, é uma boa experiência do usuário pausar a reprodução de audiolivros se o Assistente estiver respondendo a uma consulta do usuário.

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

Idioma das legendas especificadas por voz

Quando um usuário não declara explicitamente o idioma das legendas, o idioma usado é o mesmo em que o comando foi falado. Nesses cenários, o parâmetro isSuggestedLanguage da mensagem recebida indica se o idioma associado foi sugerido ou explicitamente solicitado pelo usuário.

Por exemplo, isSuggestedLanguage é definido como true para o comando "OK Google, ativar legendas", porque o idioma foi inferido pelo idioma em que o comando foi falado. Se o idioma for explicitamente solicitado, como em "Ok Google, ativar legendas em inglês", isSuggestedLanguage será definido como false.

Metadados e transmissão de voz

Embora os comandos de voz sejam processados pelo Web Receiver por padrão, você precisa garantir que os metadados do seu conteúdo estejam completos e precisos. Isso garante que os comandos de voz sejam processados corretamente pelo Assistente e que os metadados sejam exibidos em novos tipos de interface, como o app Google Home, e smart displays, como o Google Home Hub.

Transferência de stream

Observação: os receptores de áudio na Web são compatíveis com a expansão de stream por padrão, em que outros dispositivos compatíveis com Cast são adicionados à sessão. Os receptores de vídeo na Web precisam executar as etapas desta seção para oferecer suporte à transferência de stream.

Preservar o estado da sessão é a base da transferência de stream, em que os usuários podem mover streams de áudio e vídeo existentes entre dispositivos usando comandos de voz, app Google Home ou Smart Displays. A mídia para de tocar em um dispositivo (a fonte) e continua em outro (o destino). Qualquer dispositivo de transmissão com o firmware mais recente pode servir como origens ou destinos em uma transferência por streaming.

O fluxo de eventos para transferência de stream é:

1. No dispositivo de origem:
   1. A mídia é interrompida.
   2. O aplicativo Web Receiver recebe um comando para salvar o estado atual da mídia.
   3. O aplicativo Web Receiver está desativado.
2. No dispositivo de destino:
   1. O aplicativo Web Receiver é carregado.
   2. O aplicativo Web Receiver recebe um comando para restaurar o estado da mídia salva.
   3. A mídia é retomada.

Os elementos do estado da mídia incluem:

• Posição ou carimbo de data/hora específico da música, vídeo ou item de mídia.
• É o local em uma fila mais ampla, como uma playlist ou uma rádio de artista.
• O usuário autenticado.
• Estado da reprodução (por exemplo, em reprodução ou pausada).

Como ativar a transferência de stream

Para implementar a transferência de stream do Web Receiver:

1. Atualize supportedMediaCommands com o comando STREAM_TRANSFER:

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

2. Se quiser, modifique os interceptadores das mensagens SESSION_STATE e RESUME_SESSION, conforme descrito em Como preservar o estado da sessão. Substitua-os apenas se dados personalizados precisarem ser armazenados como parte do snapshot da sessão. Caso contrário, a implementação padrão para preservar estados da sessão será compatível com a transferência de stream.

Como preservar o estado da sessão

O SDK do Web Receiver oferece uma implementação padrão para apps do Web Receiver para preservar estados da sessão, tirando um snapshot do status de mídia atual, convertendo o status em uma solicitação de carregamento e retomando a sessão com a solicitação de carregamento.

A solicitação de carregamento gerada pelo Web Receiver pode ser modificada no interceptador de mensagens SESSION_STATE, se necessário. Se você quiser adicionar dados personalizados à solicitação de carregamento, coloque-os em 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;
    });

Os dados personalizados podem ser recuperados de loadRequestData.customData no interceptador da mensagem 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;
    });

Pré-carregamento de conteúdo

O Web Receiver aceita o pré-carregamento de itens de mídia após o item de reprodução atual na fila.

A operação de pré-carregamento faz o download de vários segmentos dos próximos itens. A especificação é feita no valor preloadTime no objeto QueueItem (se não for fornecido, o padrão será 20 segundos). O tempo é expresso em segundos, em relação ao fim do item em reprodução no momento . Somente valores positivos são válidos. Por exemplo, se o valor for 10 segundos, esse item será pré-carregado 10 segundos antes da conclusão do item anterior. Se o tempo para pré-carregamento for maior que o tempo restante no currentItem, o pré-carregamento será realizado assim que possível. Portanto, se um valor muito grande de pré-carregamento for especificado no queueItem, será possível conseguir o efeito de sempre que reproduzirmos o item atual, já estamos pré-carregando o próximo item. No entanto, deixamos a configuração e a escolha disso para o desenvolvedor, já que esse valor pode afetar a largura de banda e o desempenho de streaming do item em reprodução.

O pré-carregamento funcionará para conteúdo de streaming HLS, DASH e Smooth por padrão.

Arquivos de áudio e vídeo MP4 normais, como MP3, não serão pré-carregados, já que os dispositivos de transmissão são compatíveis com apenas um elemento de mídia e não podem ser usados para pré-carregamento enquanto um item de conteúdo existente ainda estiver sendo reproduzido.

Mensagens personalizadas

A troca de mensagens é o principal método de interação para aplicativos Web Receiver.

Um remetente emite mensagens para um Web Receiver usando as APIs do remetente para a plataforma em que o remetente está sendo executado (Android, iOS, Web). O objeto de evento (que é a manifestação de uma mensagem) transmitido aos listeners de eventos tem um elemento de dados (event.data) em que os dados assumem as propriedades do tipo de evento específico.

Um aplicativo de receptor da Web pode optar por ouvir mensagens em um namespace especificado. Por fazer isso, o aplicativo Web Receiver é compatível com esse protocolo de namespace. Cabe aos remetentes conectados que querem se comunicar nesse namespace para usar o protocolo apropriado.

Todos os namespaces são definidos por uma string e precisam começar com "urn:x-cast:" seguido por qualquer string. Por exemplo, "urn:x-cast:com.example.cast.mynamespace".

Observação: o namespace da mensagem de mídia "urn:x-cast:com.google.cast.media" é reservado. Mensagens de mídia enviadas usando as APIs do Google Cast no remetente e no Web Receiver usam o protocolo de namespace de mídia por convenção. Consulte Mídia e players para saber mais sobre mensagens de mídia.

Veja um snippet de código para que o Web Receiver detecte mensagens personalizadas de remetentes conectados:

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

Da mesma forma, os aplicativos Web Receiver podem manter remetentes informados sobre o estado do Web Receiver enviando mensagens para remetentes conectados. Um aplicativo Web Receiver pode enviar mensagens usando sendCustomMessage(namespace, senderId, message) em CastReceiverContext. Um Web Receiver pode enviar mensagens para um remetente individual em resposta a uma mensagem recebida ou devido a uma alteração no estado do aplicativo. Além de mensagens de ponto a ponto (com um limite de 64 KB), um Web Receiver também pode transmitir mensagens para todos os remetentes conectados.

Google Cast para dispositivos de áudio

Consulte o guia do Google Cast para dispositivos de áudio para compatibilidade com a reprodução somente de áudio.

Android TV

Esta seção discute como o Google Web Receiver usa suas entradas como reprodução e a compatibilidade com o Android TV.

Como integrar o aplicativo ao controle remoto

O Google Web Receiver executado no dispositivo Android TV traduz as entradas de controle do dispositivo (ou seja, controle remoto portátil) como mensagens de reprodução de mídia definidas para o namespace urn:x-cast:com.google.cast.media, conforme descrito em Mensagens de reprodução de mídia. Seu aplicativo precisa ser compatível com essas mensagens para controlar a reprodução de mídia do aplicativo e permitir o controle de reprodução básico a partir das entradas de controle do Android TV.

Diretrizes de compatibilidade do Android TV

Veja algumas recomendações e armadilhas comuns a serem evitadas para garantir que o aplicativo seja compatível com a Android TV:

• Lembre-se de que a string do user agent contém "Android" e "CrKey". Alguns sites podem redirecionar o usuário a um site exclusivo para dispositivos móveis porque ele detecta o rótulo "Android". Não presuma que "Android" na string de user agent sempre indica um usuário de dispositivo móvel.
• A pilha de mídia do Android pode usar GZIP transparente para buscar dados. Verifique se os dados de mídia podem responder a Accept-Encoding: gzip.
• Os eventos de mídia HTML5 do Android TV podem ser acionados em momentos diferentes do Chromecast. Isso pode revelar problemas que estavam ocultos no Chromecast.
• Ao atualizar a mídia, use eventos relacionados à mídia acionados por elementos <audio>/<video>, como timeupdate, pause e waiting. Evite usar eventos relacionados à rede, como progress, suspend e stalled, porque eles dependem da plataforma. Consulte Eventos de mídia para mais informações sobre como processar eventos de mídia no seu receptor.
• Ao configurar os certificados HTTPS do site do receptor, inclua certificados de CA intermediários. Consulte a página de teste de SSL da Qualsys (em inglês) para verificar se o caminho de certificação confiável do seu site inclui um certificado de CA chamado "download extra", que pode não ser carregado em plataformas baseadas no Android.
• Embora o Chromecast exiba a página receptora em um plano gráfico de 720p, outras plataformas de transmissão, incluindo a Android TV, podem exibir a página em até 1080p. Verifique se a página do receptor é dimensionada corretamente em diferentes resoluções.