为强制门户登录实现 Android 自定义标签页

Android 自定义标签页可直接在强制门户（例如机场、酒店和飞机上的强制门户）的网络登录流程中提供功能齐全、安全且无缝的浏览器体验。通过将用户的主浏览器集成到身份验证流程中，自定义标签页可实现高级功能，包括一键自动填充凭据和付款信息、受 DRM 保护的流式传输，以及为使用 VPN 和专用 DNS 等安全功能的用户提供一致的连接。如需详细了解自定义标签页，请参阅 Android 自定义标签页概览。

相较于旧版 WebView 的优势

通过使用自定义标签页集成用户的主浏览器，可以解决网络运营商基于旧版 WebView 的身份验证流程中固有的多项功能限制：

  • 简化的交易流程：该界面支持一键式自动填充凭据和已存储的付款信息，从而减少登录过程中的手动数据输入。（请参见图 1。）
  • 媒体兼容性：该平台支持受 DRM 保护的内容（例如 Widevine），可直接在门户内播放加密的视频流。（请参见图 2。）
  • 支持安全配置：对于使用 VPN 或专用 DNS 的设备，自定义标签页可保持门户网站功能正常运行，而这些安全功能通常会导致标准浏览器重定向失败。
  • 界面一致性：自定义标签页直接与系统浏览器集成，提供与完整浏览器会话中相同的实用工具和界面元素。
  • 后台持久性：门户在后台保持运行，在整个连接期间充当持久的接入点。

强制门户手动输入和自动填充

图 1. 手动输入（WebView）与自动填充（自定义标签页）。

强制门户视频播放

图 2. 无视频（WebView）与视频播放（自定义标签页）。

自定义标签页发现和连接流程

虽然自定义标签页提供接口，但强制门户 API 会管理发现到连接的智能流程：

  1. 发现：网络使用 DHCP 选项 114 宣传其 API 支持。
  2. 互动：Android 设备查询 API 端点以获取包含网络状态的 JSON 载荷。
  3. 连接：如果 JSON 响应指示使用自定义标签页，系统会在高性能浏览器环境中打开门户，而不是在基本系统窗口中打开。

借助强制门户 API，Android 设备可以使用 captive 字段检测是否存在强制门户。该 API 将 venue-info-url 和 seconds-remaining 等其他字段集成到 Android 系统界面中。

强制门户发现到连接流程

图 3. 强制门户 API 发现到连接流程。

启用 Android 自定义标签页

为了支持自定义标签页流程，网络运营商必须实现 Captive Portal API，并通过 JSON 配置选择启用。

要求

如需为强制门户登录启用自定义标签页，需要满足以下条件：

  • 搭载 Android 12 及更高版本且通过 Mainline CaptivePortalLogin 模块支持 Google Play 系统更新（请参阅 Mainline）的设备。
  • 支持强制门户 API (RFC 8908)。如需了解详情，请参阅支持强制门户 API。

选择启用 Android 自定义标签页

如果您的网络已支持 Captive Portal API (RFC 8908)，请将以下键值对添加到现有 JSON 响应对象，以启用 Custom Tabs 流程：

键 值 说明
x-android-use-custom-tabs 361335020 此值表示 2026 年 1 月发布的 Captive Portal Login Mainline 模块的版本号。如果设备的模块更新版本不低于此版本，则使用 Custom Tabs 登录流程。

此 JSON 对象示例包含 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
}

以下是可用的 JSON 强制门户属性：

  • captive：如果需要身份验证，则设置为 true；如果用户已在线，则设置为 false。
  • user-portal-url：登录或付款页面的网址。
  • venue-info-url：指向您网站的链接，用于提供信息（例如航班详情或地图）。
  • seconds-remaining：表示设备预计能保持互联网连接的剩余时间（以秒为单位）。
  • x-android-use-custom-tabs：控制设备是否在可用时使用自定义标签页。

支持强制门户 API

如果您的网络不支持强制门户 API，请按以下步骤操作，以启用强制门户 API 和自定义标签页流程。

  1. 更新 DHCP 服务器配置，以包含 DHCP 选项 114。

    • 值：提供包含强制门户信息的动态生成的 JSON 文件的完整 HTTPS 网址（例如 https://api.yourvenue.com/status）。

    • 结果：当 Android 设备加入网络时，它会查询所提供的 API，而不是等待浏览器重定向。

  2. 将您的 API 服务器配置为使用 JSON 文件响应所提供网址上的 HTTP GET 请求，该 JSON 文件会告知设备门户的当前状态。

    • HTTPS 要求：您的 API 服务器必须使用有效的 HTTPS 证书。

    • 安全回退：如果证书无效或自签名，设备会回退到旧版强制门户行为。

Android 强制门户检测行为

强制门户 API 提供了一种可靠的替代方案，可用于取代标准 Android 网络探测来检测强制门户是否存在，从而绕过常见的不一致情况。

Android 设备会向特定验证网址同时发送 HTTP 和 HTTPS 探测，以检查网络访问权限。如果探测成功情况不一致（例如，HTTP 成功但 HTTPS 失败），则会导致部分连接状态，这可能会阻止自动显示登录应用。

强制门户 API 通过以下检测行为使检测更加可靠：

  • 如果 API 报告 "captive": true，系统会识别出它位于门户后面，并跳过标准探测，立即显示登录界面。
  • 如果 API 报告 "captive": false，系统会继续进行标准探测，要求 HTTP 和 HTTPS 探测均成功，然后才能确认完全的互联网访问权限。