D DOKUBASIS
Blog Dev

Depuração de localhost no Android: reencaminhamento de portas, controladores ADB e a janela RSA em falta

Um botão sobreposto no navegador móvel, uma aplicação Spring Boot protegida por uma barreira OAuth rigorosa e um computador Windows que não reconhece o smartphone. Aquilo que parece uma pequena correção de CSS transforma-se rapidamente numa odisseia de depuração. Uma análise aprofundada para programadores web que enfrentam problemas com o reencaminhamento de portas do Chrome, controladores ADB com falhas e janelas de depuração USB que se recusam a aparecer.

Quem trabalha em desenvolvimento web conhece bem este fenómeno: a aplicação web tem um aspeto excelente no navegador do monitor do computador. A vista móvel nas DevTools do Chrome também não apresenta erros. No entanto, ao abrir a página num smartphone Android real, por exemplo no Edge ou no Chrome, alguns elementos importantes da interface desaparecem subitamente ou os botões ficam sobrepostos.

O problema: erros de CSS, Edge móvel e a armadilha do OAuth

Muitas vezes, o culpado é rapidamente identificado: a propriedade CSS height: 100vh. Os navegadores móveis, sobretudo os que têm uma barra de endereço na parte inferior, como o Edge móvel, calculam frequentemente este valor com base na altura máxima do ecrã. Ao fazê-lo, ignoram a barra de menu dinâmica que aparece e desaparece durante o deslocamento. O resultado: o layout prolonga-se para além da parte inferior da área visível.

Hoje, a solução é geralmente trivial: utilizar height: 100dvh (Dynamic Viewport Height), que tem estas barras corretamente em conta.

Mas como testar esta correção localmente quando a aplicação é mais complexa?

Porque é que o Cloudflare Tunnel falha frequentemente com OAuth

Para testes móveis temporários, muitos programadores recorrem a serviços como os Cloudflare Quick Tunnels (trycloudflare.com). O problema é que estes geram um subdomínio novo e aleatório sempre que são iniciados.

Se a sua aplicação, como um backend Spring Boot, estiver protegida por um início de sessão OAuth2 (Google, GitHub, Auth0), o fornecedor exige um URI de redirecionamento previamente registado de forma rigorosa. Um URL aleatório da Cloudflare provoca um erro «Redirect URI mismatch». Mesmo desativar temporariamente a segurança no código é muitas vezes impossível quando dados essenciais da aplicação, como as funções dos utilizadores, são carregados diretamente a partir do perfil OAuth autenticado.

A solução mais elegante é o reencaminhamento de portas do Chrome através da depuração USB. O smartphone encaminha os seus pedidos pelo cabo USB para o localhost do computador de desenvolvimento. Para o fornecedor OAuth, o redirecionamento continua a ser o localhost:8080 limpo e autorizado.

No entanto, no Windows, o caminho até lá costuma ser acidentado.

Obstáculo 1: o Gestor de Dispositivos do Windows e a ausência de controladores

O primeiro passo lógico leva às opções de programador do dispositivo Android: ativar a depuração USB e ligar o telemóvel ao computador por cabo. Porém, nas DevTools do Chrome, em chrome://inspect/#devices, não aparece absolutamente nada.

Uma consulta ao Gestor de Dispositivos do Windows revela geralmente o problema: embora o smartphone seja reconhecido como dispositivo de armazenamento MTP, a interface de depuração está em falta ou assinalada com um ponto de exclamação amarelo («ADB Interface»). O Windows simplesmente não tem os controladores adequados para a depuração no Android.

Instalar controladores ADB como administrador

Para instalar corretamente o controlador em todo o sistema, é indispensável iniciar o Gestor de Dispositivos com privilégios de administrador. Caso contrário, o Windows impede a atribuição manual do controlador.

  1. Abra a Linha de Comandos como administrador: Prima a tecla Windows, escreva cmd, clique com o botão direito do rato em «Linha de Comandos» e selecione «Executar como administrador».
  2. Force a abertura do Gestor de Dispositivos: Introduza o comando devmgmt.msc e prima Enter.
  3. Transfira e instale o controlador: Transfira o Google USB Driver oficial e extraia o ficheiro ZIP.
  4. No Gestor de Dispositivos, clique com o botão direito do rato no «Dispositivo desconhecido» assinalado com o ponto de exclamação, selecione Atualizar controlador, depois Procurar controladores no meu computador e escolha a pasta que extraiu.

Após a instalação bem-sucedida, o dispositivo deverá aparecer corretamente como «Android Composite ADB Interface».

Obstáculo 2: «Offline» - porque é que a janela de depuração USB não aparece

Os controladores estão instalados e o telemóvel está ligado, mas o Chrome continua a apresentar o dispositivo apenas como Offline em chrome://inspect. E acrescenta a mensagem fatal: «Pending authentication: please accept debugging session on the device.»

Neste momento, deveria aparecer no smartphone a chamada janela RSA: «Permitir depuração USB? A impressão digital da chave RSA do computador é…» Sem esta confirmação criptográfica, o Android bloqueia terminantemente o acesso do computador. Contudo, o ecrã permanece vazio. Nem a revogação das autorizações de depuração nem a utilização de outro smartphone resolvem o problema.

O conflito entre o Chrome e o daemon ADB

A resposta está na arquitetura do Chrome. O navegador inclui a sua própria rotina integrada de deteção USB. Esta depende da comunicação em segundo plano com o daemon ADB (adb.exe, Android Debug Bridge). Contudo, se este serviço em segundo plano não estiver em execução no computador, tiver bloqueado ou o Chrome não tiver permissões para o acionar corretamente, o handshake RSA necessário nunca é enviado pela porta USB.

O smartphone aguarda um pedido de autorização que o computador nunca envia.

A correção: forçar manualmente o handshake ADB

Quando o Chrome falha, é necessário inicializar manualmente a ligação ao hardware através da linha de comandos. Para isso, precisamos das ferramentas oficiais da Google, sem qualquer camada adicional.

Guia passo a passo para resolver o problema

  1. Transfira as Platform-Tools: Transfira as Android Platform-Tools. Não precisam de ser instaladas. Basta extrair o ficheiro ZIP para uma pasta, por exemplo no Ambiente de Trabalho.
  2. Verifique o modo MTP no smartphone (importante!): Por motivos de segurança, como a proteção contra «Juice Jacking» em postos de carregamento públicos, as versões modernas do Android bloqueiam as linhas de dados quando o dispositivo está definido como «Apenas carregar». Nas definições USB do telemóvel, selecione obrigatoriamente «Transferência de dados» (MTP).
  3. Inicie o ADB manualmente: Abra o Explorador de Ficheiros do Windows na pasta para onde extraiu as Platform-Tools. Clique na barra de endereço, na parte superior, escreva cmd e prima Enter. O terminal abre-se exatamente nesse diretório.
  4. O comando decisivo: Introduza o comando seguinte e prima Enter:
adb devices

O que acontece em segundo plano: O sistema apresenta agora: * daemon not running; starting now at tcp:5037. O daemon ADB é forçado a iniciar e procura ativamente nas portas USB. Utiliza o controlador do Windows que foi anteriormente corrigido e envia o handshake RSA para o smartphone.

O resultado: Exatamente no momento em que o comando é executado, aparece no ecrã do smartphone a tão aguardada janela «Permitir depuração USB?».

O final: ativar e testar o reencaminhamento de portas

Depois de confirmar «Permitir sempre a partir deste computador» na janela apresentada no telemóvel, a configuração está concluída:

  1. Regresse ao Chrome e aceda a chrome://inspect/#devices. A mensagem «Offline» desapareceu e o dispositivo aparece como ativo.
  2. Junto ao dispositivo, clique em «Reencaminhamento de portas…».
  3. Introduza a porta 8080 ou a porta da sua aplicação Spring Boot.
  4. Introduza localhost:8080 como endereço de destino.
  5. Selecione «Ativar reencaminhamento de portas» e confirme.

Agora, abra o Edge ou o Chrome móvel no smartphone e introduza http://localhost:8080 na barra de endereço. O tráfego é encaminhado em segurança pelo cabo USB para o computador. A aplicação é carregada, o redirecionamento OAuth para localhost funciona perfeitamente, as funções são carregadas corretamente a partir da base de dados e pode finalmente dedicar-se à correção do erro de CSS inicial.

Conclusão: Quando tecnologias web como OAuth e CSS se cruzam com interfaces de hardware como ADB e protocolos USB, os sintomas dos erros são muitas vezes difíceis de interpretar. Uma janela RSA que não aparece raramente significa que o smartphone está avariado; geralmente, indica que o daemon ADB está silenciado. Ter o comando adb devices e o modo de administrador do Gestor de Dispositivos do Windows no seu conjunto de ferramentas evita horas de diagnóstico infrutífero.