Esta página foi traduzida pela API Cloud Translation.

Compartilhamento de guias aprimorado com a alça de captura

François Beaufort

Elad Alon

Compatibilidade com navegadores

A plataforma da Web agora vem com o Capture Handle, um mecanismo que facilita a colaboração entre apps da Web capturados e de captura. O identificador de captura permite que um app de captura identifique o app de captura de forma ergonômica e confiável. (Se o app de captura tiver ativado essa opção.)

Alguns exemplos ilustram os benefícios.

Exemplo 1: se um app da Web de videoconferência estiver capturando um app da Web de apresentação, ele poderá expor controles para o usuário navegar entre os slides. Como os controles são incorporados diretamente no app da Web de videoconferência, o usuário não precisa alternar repetidamente entre a guia de videoconferência e a guia apresentada. Com essa carga aliviada, o usuário agora pode se concentrar mais na apresentação.

Exemplo 2: o efeito "salão de espelhos" ocorre quando uma superfície capturada é renderizada de volta ao local que está sendo capturado. Se o usuário escolher capturar a guia em que uma chamada de videoconferência está acontecendo e o app da Web de videoconferência renderizar uma visualização local, esse efeito será observado. Com o Capture Handle, a autocaptura pode ser detectada e mitigada, por exemplo, pelo app da Web que suprime a visualização local.

Ilustração do efeito da galeria de espelhos

Sobre o identificador de captura

O identificador de captura é dividido em duas partes complementares:

Os apps da Web capturados podem ativar a exposição de determinadas informações para algumas origens com navigator.mediaDevices.setCaptureHandleConfig().
Os apps da Web de captura podem ler essas informações com getCaptureHandle() em objetos MediaStreamTrack.

Lado capturado

Os aplicativos da Web podem expor informações a possíveis aplicativos da Web. Para isso, chame navigator.mediaDevices.setCaptureHandleConfig() com um objeto opcional que consiste nestes membros:

handle: pode ser qualquer string de até 1.024 caracteres.
exposeOrigin: se true, a origem do app da Web capturado pode ser exposta para capturar apps da Web.
permittedOrigins: os valores válidos são (i) uma matriz vazia, (ii) uma matriz com o item único "*" ou (iii) uma matriz de origens. Se permittedOrigins consistir no único item "*", CaptureHandle será observável por todos os apps da Web de captura. Caso contrário, ele só é observado para capturar apps da Web com origem em permittedOrigins.

O exemplo a seguir mostra como expor um UUID gerado aleatoriamente como um identificador e a origem para qualquer app da Web de captura.

const config = {
  handle: crypto.randomUUID(),
  exposeOrigin: true,
  permittedOrigins: ['*'],
};
navigator.mediaDevices.setCaptureHandleConfig(config);

O app da Web capturado não sabe se está sendo capturada. A menos que o app da Web de captura use informações CaptureHandle para estabelecer a comunicação com o app da Web capturado (usando mensagens por um worker ou uma infraestrutura de nuvem compartilhada, por exemplo).

Lado da captura

O app da Web de captura armazena um MediaStreamTrack de vídeo e pode ler as informações do identificador de captura chamando getCaptureHandle() nesse MediaStreamTrack. Essa chamada vai retornar null se nenhum identificador de captura estiver disponível ou se o app da Web de captura não tiver permissão para fazer a leitura. Se um handle de captura estiver disponível e o app da Web de captura for adicionado a permittedOrigins, essa chamada vai retornar um objeto com os seguintes membros:

handle: o valor da string definido pelo app da Web capturado com navigator.mediaDevices.setCaptureHandleConfig().
origin: a origem do app da Web capturado se exposeOrigin foi definido como true. Caso contrário, ela não é definida.

O exemplo a seguir mostra como ler as informações do identificador de captura de uma faixa de vídeo.

// Prompt the user to capture their display (screen, window, tab).
const stream = await navigator.mediaDevices.getDisplayMedia();

// Check if the video track is exposing information.
const [videoTrack] = stream.getVideoTracks();
const captureHandle = videoTrack.getCaptureHandle();
if (captureHandle) {
  // Use captureHandle.origin and captureHandle.handle...
}

Monitore as mudanças de CaptureHandle detectando eventos "capturehandlechange" em um objeto MediaStreamTrack. As mudanças acontecem quando:

O app da Web capturado chama navigator.mediaDevices.setCaptureHandleConfig().
Uma navegação entre documentos ocorre no app da Web capturado.

videoTrack.addEventListener('capturehandlechange', event => {
  captureHandle = event.target.getCaptureHandle();
  // Consume new capture handle...
});

Segurança e privacidade

A colaboração entre apps da Web capturados e de captura é teoricamente possível hoje, incorporando "pixels mágicos" no app da Web capturado ou QR codes no stream de vídeo, por exemplo. O Identificador de captura oferece um mecanismo mais simples, confiável e seguro. Ele também permite que o app da Web capturado selecione o público-alvo, seja origens selecionadas ou toda a Web.

navigator.mediaDevices.setCaptureHandleConfig() está disponível apenas para frames principais de nível superior em contextos de navegação segura (somente HTTPS).

Exemplo

Você pode brincar com o Capture Handle executando o exemplo no Glitch. Confira o código-fonte.

Demonstrações

Algumas demonstrações estão disponíveis em:

Detecção de recursos

Para verificar se o getCaptureHandle() tem suporte, use:

if ('getCaptureHandle' in MediaStreamTrack.prototype) {
  // getCaptureHandle() is supported.
}

Para verificar se o navigator.mediaDevices.setCaptureHandleConfig() tem suporte, use:

if ('setCaptureHandleConfig' in navigator.mediaDevices) {
  // navigator.mediaDevices.setCaptureHandleConfig() is supported.
}

A seguir

Confira o que vai melhorar em breve na Web:

A captura de região permite cortar uma faixa de vídeo derivada da captura de tela da guia atual.
O foco condicional permite que o app da Web de captura instrua o navegador a mudar o foco para a superfície de exibição capturada ou evitar essa mudança de foco.

Feedback

A equipe do Chrome e a comunidade de padrões da Web querem saber sobre sua experiência com o Capture Handle.

Fale sobre o design

Há algo no identificador de captura que não funciona como você esperava? Ou há métodos ou propriedades que faltam para implementar sua ideia? Tem uma pergunta ou comentário sobre o modelo de segurança?

Envie um problema de especificação no repositório do GitHub ou adicione sua opinião a um problema existente.

Tem problemas com a implementação?

Você encontrou um bug na implementação do Chrome? Ou a implementação é diferente da especificação?

Registre um bug em https://new.crbug.com. Inclua o máximo de detalhes possível e instruções simples para reproduzi-lo. O Glitch é ótimo para compartilhar reproduções rápidas e fáceis.

Mostrar apoio

Você planeja usar o Capture Handle? Seu apoio público ajuda a equipe do Chrome a priorizar recursos e mostra a outros fornecedores de navegadores a importância de oferecer suporte a eles.

Envie um tweet para @ChromiumDev e diga onde e como você está usando.

Links úteis

Agradecimentos

Agradecemos a Joe Medley por revisar este artigo.