Implementar guias personalizadas do Android para login do portal cativo

As guias personalizadas do Android oferecem uma experiência de navegador completa, segura e integrada diretamente no fluxo de login de rede para portais cativos, como os encontrados em aeroportos, hotéis e aviões. Ao integrar o navegador principal do usuário ao processo de autenticação, as guias personalizadas ativam funcionalidades avançadas, como preenchimento automático com um toque para credenciais e pagamentos, streaming protegido por DRM e conectividade consistente para usuários com recursos de segurança, como VPNs e DNS particular. Para mais informações sobre guias personalizadas, consulte Visão geral das guias personalizadas do Android.

Benefícios em relação ao WebView legado

A integração do navegador principal do usuário usando guias personalizadas resolve várias limitações funcionais inerentes aos fluxos de autenticação legados baseados em WebView para operadores de rede:

• Transações simplificadas:a interface oferece suporte ao preenchimento automático com um toque para credenciais e informações de pagamento armazenadas, reduzindo a entrada manual de dados durante o processo de login. Confira a Figura 1.
• Compatibilidade de mídia:a plataforma é compatível com conteúdo protegido por DRM (como Widevine), permitindo a reprodução de streams de vídeo criptografados diretamente no portal. (Consulte a Figura 2.)
• Suporte para configurações de segurança:as guias personalizadas mantêm a funcionalidade do portal para dispositivos que usam VPNs ou DNS particular, recursos de segurança que geralmente causam falha nos redirecionamentos padrão do navegador.
• Consistência da interface:as guias personalizadas se integram diretamente ao navegador do sistema, oferecendo as mesmas ferramentas funcionais e elementos de interface disponíveis em uma sessão completa do navegador.
• Persistência em segundo plano:o portal permanece operacional em segundo plano, servindo como um ponto de acesso persistente durante todo o período de conexão.

Figura 1. Entrada manual (WebView) x preenchimento automático (Custom Tabs).

Figura 2. Sem vídeo (WebView) x reprodução de vídeo (Custom Tabs).

Fluxo de descoberta e conexão das guias personalizadas

Enquanto as guias personalizadas fornecem a interface, a API Captive Portal gerencia o fluxo de inteligência de descoberta para conexão:

1. Descoberta:a rede anuncia a compatibilidade com a API usando a opção 114 do DHCP.
2. Interação:o dispositivo Android consulta o endpoint da API para buscar um payload JSON que contém o status da rede.
3. Conexão:se a resposta JSON indicar o uso de guias personalizadas, o sistema vai abrir o portal em um ambiente de navegador de alto desempenho em vez de uma janela básica do sistema.

A API Captive Portal permite que dispositivos Android detectem se um portal cativo existe usando o campo captive. A API integra outros campos, como venue-info-url e seconds-remaining, à interface do sistema Android.

Figura 3. Descoberta da API Captive Portal para fluxo de conexão.

Ativar guias personalizadas do Android

Para oferecer suporte ao fluxo das guias personalizadas, os operadores de rede precisam implementar a API Captive Portal e ativar a opção na configuração JSON.

Requisitos

Para ativar as guias personalizadas no login do portal cativo, é necessário:

• Dispositivo com Android 12 ou mais recente que ofereça suporte a atualizações do sistema do Google Play (consulte Mainline) pelo módulo CaptivePortalLogin Mainline.
• Suporte à API Captive Portal (RFC 8908). Para mais detalhes, consulte Suporte à API Captive Portal.

Ativar as guias personalizadas do Android

Se a rede já for compatível com a API Captive Portal (RFC 8908), adicione o seguinte par de chave-valor ao objeto de resposta JSON atual para ativar o fluxo de guias personalizadas:

Este exemplo de objeto JSON inclui todos os atributos de portal cativo compatíveis com Android:

{
  "captive": true,
  "user-portal-url": "https://login.example.com",
  "venue-info-url": "https://venue.example.com",
  "seconds-remaining": 3600,
  "x-android-use-custom-tabs": 361335020
}

Confira abaixo os atributos de portal cativo JSON disponíveis:

• captive: definido como true se a autenticação for obrigatória ou como false se o usuário já estiver on-line.
• user-portal-url: o URL da página de login ou pagamento.
• venue-info-url: um link para seu site com informações (por exemplo, detalhes do voo ou mapas).
• seconds-remaining: indica o tempo restante (em segundos) em que o dispositivo deve manter uma conexão de Internet.
• x-android-use-custom-tabs: controla se o dispositivo usa a guia personalizada quando disponível.

Compatibilidade com a API Captive Portal

Se a rede não for compatível com a API Captive Portal, siga estas etapas para ativar a API Captive Portal e o fluxo do Custom Tabs.

1. Atualize a configuração do servidor DHCP para incluir a opção 114 do DHCP.

   • Valor:forneça o URL HTTPS completo do arquivo JSON gerado dinamicamente que contém informações do portal cativo (por exemplo, https://api.yourvenue.com/status).

   • Resultado:quando um dispositivo Android entra na rede, ele consulta a API fornecida em vez de esperar um redirecionamento do navegador.

2. Configure seu servidor de API para responder a uma solicitação HTTP GET no URL fornecido com um arquivo JSON que informa ao dispositivo o estado atual do portal.

   • Requisito de HTTPS:seu servidor de API precisa usar um certificado HTTPS válido.

   • Fallback de segurança:se o certificado for inválido ou autoassinado, o dispositivo vai voltar ao comportamento legado do portal cativo.

Comportamento da detecção de portal cativo do Android

A API Captive Portal oferece uma alternativa confiável às sondagens de rede padrão do Android para detectar a existência de um portal cativo, evitando inconsistências comuns.

Os dispositivos Android verificam o acesso à rede enviando sondagens HTTP e HTTPS simultâneas para URLs de validação específicos. O sucesso inconsistente da sondagem (por exemplo, HTTP bem-sucedido, mas HTTPS com falha) resulta em um estado de conectividade parcial, que pode impedir a exibição automática do app de login.

A API Captive Portal torna a detecção mais confiável usando o seguinte comportamento de detecção:

• Se a API informar "captive": true, o sistema vai reconhecer que ela está atrás de um portal e vai pular as sondagens padrão para mostrar imediatamente a interface de login.
• Se a API informar "captive": false, o sistema vai continuar com as sondagens padrão, exigindo que as sondagens HTTP e HTTPS sejam bem-sucedidas antes de confirmar o acesso total à Internet.