Pular para o conteúdo
Guida

Visualização remota

A visualização remota é um recurso de operações remotas para visualizar uma guia do navegador Guida a partir de outro cliente. Ela usa a ponte Chrome DevTools Protocol do WebView2 para capturar quadros da guia e um fluxo WebSocket para enviar quadros e mensagens de entrada.

A visualização remota é útil para painéis de navegador, interfaces leves de controle e observadores de rede privada que precisam ver o que um nó Guida está fazendo sem estar no desktop.

Requisitos

Seção intitulada “Requisitos”
  • A API de operações remotas precisa estar habilitada.
  • O cliente precisa conseguir alcançar o endereço e a porta de bind das operações remotas.
  • Entrada só é aceita quando a sessão é iniciada com allowInput: true.

O Guida não autentica clientes de visualização remota separadamente das operações remotas. Proteja o canal externamente.

Iniciar uma sessão

Seção intitulada “Iniciar uma sessão”

Chame browser.remoteView.start por POST /api/ops/rpc.

{
  "jsonrpc": "2.0",
  "id": "view-1",
  "method": "browser.remoteView.start",
  "params": {
    "tabId": "optional-tab-id",
    "transport": "websocket",
    "allowInput": true,
    "quality": 75,
    "maxFps": 15
  }
}

Omitir tabId usa a guia ativa do navegador.

O resultado inclui sessionId, tabId, webSocketUrl, frameFormat, inputEnabled, availableTransports, nodeId e nodeName.

Mensagens WebSocket

Seção intitulada “Mensagens WebSocket”

Conecte-se ao webSocketUrl retornado.

Mensagens do servidor para o cliente incluem:

  • session.started
  • frame
  • error
  • pong
  • session.stopped

Mensagens frame contêm dados JPEG e metadados da área de visualização, incluindo dimensões necessárias para mapear coordenadas do ponteiro no cliente de volta à área de entrada do Guida.

Mensagens do cliente para o servidor incluem:

{ "type": "ping" }
{ "type": "session.stop" }
{ "type": "input.pointer", "event": "down", "x": 120, "y": 80, "button": "left", "clickCount": 1 }
{ "type": "input.pointer", "event": "up", "x": 120, "y": 80, "button": "left", "clickCount": 1 }
{ "type": "input.wheel", "x": 120, "y": 80, "deltaX": 0, "deltaY": -240 }
{ "type": "input.key", "event": "down", "key": "Enter", "code": "Enter" }
{ "type": "input.text", "text": "hello" }

Mapeamento de coordenadas

Seção intitulada “Mapeamento de coordenadas”

O cliente precisa mapear coordenadas da imagem renderizada de volta aos metadados de área de visualização enviados em cada quadro. Não presuma que o tamanho do elemento de imagem, as dimensões JPEG e a área de entrada do navegador sejam idênticos.

Isso importa especialmente quando:

  • o cliente ajusta o quadro dentro de um painel redimensionável
  • o Guida usa uma área de visualização desktop ajustada
  • o Guida usa uma predefinição de emulação mobile ou tablet
  • o quadro transmitido inclui deslocamentos de navegador/dispositivo

Mantenha esse mapeamento em um único utilitário no cliente. Entrada de ponteiro deve ser enviada no espaço de coordenadas de entrada do Guida, não em pixels CSS brutos da interface web ao redor.

Entrada mobile e touch

Seção intitulada “Entrada mobile e touch”

Quando a guia do Guida usa uma predefinição mobile ou tablet, o Guida ativa emulação de dispositivo e toque. A visualização remota então encaminha entrada no estilo ponteiro como entrada de toque CDP quando apropriado.

Gestos de roda podem ser traduzidos em gestos de rolagem por toque para áreas de visualização mobile. Clientes ainda devem enviar as mesmas mensagens do protocolo de visualização remota; o Guida decide como despachá-las para CDP com base no modo de área de visualização atual da guia.

Indicador da guia observada

Seção intitulada “Indicador da guia observada”

Enquanto uma sessão de visualização remota está ativa, o Guida mostra um indicador no aplicativo sobre a guia observada para que o usuário local veja que ela está sendo visualizada ou controlada.

Sessões somente visualização indicam visualização remota. Sessões com entrada habilitada indicam controle remoto. O indicador faz parte do chrome do navegador do Guida, não do conteúdo arbitrário da página, e é removido quando a sessão termina.

Parar uma sessão

Seção intitulada “Parar uma sessão”

Chame browser.remoteView.stop:

{
  "jsonrpc": "2.0",
  "id": "view-stop-1",
  "method": "browser.remoteView.stop",
  "params": {
    "sessionId": "remote-view-session-id",
    "reason": "operator closed viewer"
  }
}

Use browser.remoteView.status para inspecionar sessões ativas.

Limite de transporte

Seção intitulada “Limite de transporte”

O primeiro transporte é WebSocket porque é simples e funciona bem em redes privadas como NetBird. O comando de visualização remota e o protocolo de entrada são deliberadamente separados do transporte para que um transporte WebRTC futuro possa reutilizar o mesmo modelo de sessão.

Próximos passos

Seção intitulada “Próximos passos”