文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>边缘安全加速平台 EO>DDoS 与 Web 防护>Web 防护>Bot 管理>客户端认证（Beta）>集成指引>步骤 2：集成客户端认证>浏览器和 WebView 端集成步骤

浏览器和 WebView 端集成步骤

最近更新时间：2025-09-23 11:44:51

我的收藏

本页目录：

EdgeOne 提供适用于 Web 网站的客户端认证 SDK，可以通过前端 JavaScript 的形式集成到网页中，实现对浏览器用户的透明验证。
说明：
如需快速集成用户无感（不可见的纯后台）认证方式到简单的 Web 服务上，您可关注 SDK 集成与认证调用 部分。
如您使用的认证方式有用户可见的交互组件，请同时关注 适配使用交互式认证 部分，以便更好地提供更好的站点交互体验。
如您的站点服务同时使用了第三方域名 API，请进一步关注 CORS 支持：配置自动认证范围 部分，以确保站点可以正常访问第三方服务。

浏览器兼容性

客户端认证 SDK 支持现代主流浏览器环境，包括移动端 WebView。建议的最低版本如下：
Chrome ≥ 90
Firefox ≥ 90
Safari ≥ 11
Edge ≥ 90
移动端 WebView (iOS ≥ 11，Android WebView ≥ 67)
Opera ≥ 76
说明：
旧版浏览器（尤其是不支持 Promise、Fetch 或 Crypto API 的浏览器）可能无法正常运行 SDK。
当前仅支持基于 HTTPS 协议的 HTML 页面响应集成 SDK。

SDK 集成与认证调用

通过以下任一方式，可将 SDK 集成至页面。当浏览器或 WebView 组件成功加载 SDK 后，会在 window 对象中实例化 EOClientSecurityKit 全局对象。开发者可通过此对象访问 SDK 接口，进行进一步配置和控制。
通过 HTML 页面注入 JavaScript （推荐）
手动集成适配
通过 JavaScript 注入的方式可以高效便捷地完成浏览器和 WebView 集成，适用于由 EdgeOne 平台提供或代理的 HTML 页面，可最大程度减少手动干预。

适用场景

WebView 客户端或浏览器需访问受 EdgeOne 保护的 HTML 页面及 API 端点。（HTML 页面通过 EdgeOne 代理分发）

集成方式

无需前端代码修改。在 EdgeOne 云控制台配置注入规则，启用 JavaScript 注入功能。
客户端认证 SDK 将被封装在一段 JavaScript 代码片段中，在响应指定 HTML 页面时，自动注入至 HTML 内容中。当客户端继续访问 EdgeOne 加载页面内容或发起 AJAX 请求时，该代码片段将根据认证规则要求运行对应认证机制，并自动提交认证结果。当配合无感客户端认证方式使用时，上述认证过程不需要对页面资源进行特殊调整或适配。

SDK 工作原理

SDK 代码注入并加载后，会自动拦截页面中的 XMLHttpRequest 和 fetch API 调用。SDK 将透明处理来自 EdgeOne 服务器的 HTTP 428 挑战，并在认证成功后自动将认证令牌附加到后续请求头中，实现客户端认证自动化。

配置 JavaScript 注入范围

您可使用 JavaScript 注入规则 配置注入 JavaScript 的范围。通过配置规则优先级、匹配条件，您可以指定 EdgeOne 对特定资源注入 JavaScript 代码片段，或者跳过注入，以同时满足最佳的访问性能和认证效果。
请避免在以下场景开启 JavaScript 注入，避免造成业务异常：
非 HTTPS 的页面路径；
API 路径或移动端会访问的路径；
WebSocket 服务路径；
启用了边缘函数的路径；
启用了主动特征识别的路径；
配置规则时，可指定域名（Host）、URL 路径、请求方法等条件。例如，只对某个二级域名生效，或者只针对特定路径（如 /checkout）生效。此外，也可根据需要匹配 Cookie 或请求头等，提高灵活性。仅当请求匹配所有设置的条件时，才会进行脚本注入。

示例场景：为站点所有 HTML 页面自动部署 JavaScript 注入，认证浏览器客户端

对访问电商站点 www.buyexample.com 站点下所有 HTML 页面的浏览器和 WebView 客户端默认进行安全认证，以便对接口部署认证策略。

操作步骤

注意：
1. 开始进行此处操作步骤前，请先 配置认证方式。
2. 在生产环境进行配置前，请务必使用测试域名进行部署并测试兼容性。
1. 登录 边缘安全加速平台 EO 控制台，在左侧菜单栏中，进入服务总览，单击网站安全加速内需配置的站点。
2. 单击安全防护 > 客户端认证。单击认证 SDK 集成分页，在浏览器集成：注入 JavaScript 选项中，单击添加规则进入集成规则配置界面。



3. 填写规则名称，配置判断条件和 JavaScript 注入选项。以示例场景为例，在匹配条件选项中，选择请求域名匹配；在 JavaScript 注入选项中，选择注入 JavaScript。当一个请求匹配多个规则时，以优先级高（数值低）的规则处置方式为准。



4. 单击保存并发布后，规则将部署生效。
适用于无法通过 EdgeOne 平台进行 JavaScript 注入的特定场景，例如本地文件加载或多 CDN 分发。

适用场景

网页从本地存储（如文件系统、应用内部存储）加载。
静态站点文件通过多个不受 EdgeOne 控制的 CDN 分发。
开发者需对 SDK 加载和初始化过程进行更精细控制。

实现方式

确保客户端设备可访问互联网。将以下 <script> 标签直接插入目标 HTML 页面 <head> 部分（或 <body> 结束标签前）：
注意：
请确保 src 属性指向正确的 SDK 分发地址。
<script src="https://cdnstatic.tencentcs.com/edgeone/security/client-attestation/eoclientsecuritykit.min.js"></script>

工作原理

<script> 标签加载执行后，eoclientsecuritykit.min.js 将运行并拦截页面中通过 AJAX（XHR 和 Fetch API）发出的请求。SDK 将处理认证挑战、获取认证令牌，并自动附加到后续请求中，从而保护 API 端点。

适配使用交互式认证（可选）

在一些客户端认证场景中，EdgeOne SDK 需要特定的运行环境支持，例如：
当认证流程需要用户交互（如验证码）
执行计算密集型任务（如工作量证明）
此类场景中，需要为 SDK 提供加载 JavaScript 必要的运行环境（WebView 或浏览器）。本节将详细阐述如何适配这些交互式认证场景，包括 WebView 的使用方式及认证 UI 的渲染选项。

使用 WebView 运行交互式或基于 JS 的认证

当认证器需要渲染交互式验证码 (CAPTCHA) 或运行基于 JavaScript 的加密工作量证明 (Proof-of-Work) 挑战时，SDK 要求在 API 参数中提供一个 WebView 实例。这意味着开发者需在应用程序中预先分配一个 WebView 实例，并在调用认证 API 时将其作为参数传递给 SDK。

交互式认证场景

部分认证器（例如，使用嵌入式或弹出式交互设置的 TC-CAPTCHA）需 WebView 实例来渲染其交互界面。该 WebView 实例将在应用内部显示验证码页面，因此需预先设置以确保正确显示。
嵌入式交互认证
弹出式交互认证
以固定区块形式显示在设备屏幕上。为确保 UI 正确显示且不影响用户体验，开发者必须预设渲染窗口的大小、层叠顺序和对齐方式。请注意，嵌入式认证 GUI 不随屏幕视图缩放。
说明：腾讯云验证码（TC-CAPTCHA）嵌入式模式建议预留至少 300x230 像素空间，以获得最佳渲染效果和用户交互体验。
在认证被调用时，以浮动窗口形式显示在设备屏幕上。与嵌入式认证类似，渲染窗口的大小、层叠顺序和对齐方式也需预设。弹出式认证的特点是，当屏幕视图小于特定阈值时，弹出式认证 GUI 会自动缩放以适应不同屏幕尺寸。
说明：腾讯云验证码（TC-CAPTCHA）的弹出式模式的初始渲染块大小为 360x360 像素。

基于 JavaScript 的认证场景

某些认证器（例如，使用无感模式的 TC-CAPTCHA）需 WebView 实例作为 JavaScript 运行时环境，主要用于执行加密工作量证明 (PoW) 挑战。在此场景下，WebView 实例仅提供 JavaScript 执行沙箱，无需可见地渲染任何 UI。因此，传入的 WebView 实例无需可见，SDK 也不会将其用于 UI 渲染。

渲染认证所需的 UI

对于浏览器或 WebView 环境中的 H5/Web 应用，当使用交互式或可见认证时，SDK 需要一个 HTML 元素来渲染认证 UI。SDK 支持多种常见容器元素，例如 <span>、<p>、<div> 和 <section>。SDK 将根据以下优先级顺序决定认证 UI 的渲染位置：
选项一：使用选择器回调指定元素
选项二：使用 eo-client-attestation 元素 ID
选项三：默认动态创建元素
开发者可通过调用 window.EOClientSecurityKit.setClientAttestationDOMSelectorProvider(elementSelectorFunc) API 分配一个元素选择器函数。当 SDK 需要渲染认证 UI 时，将调用此函数。elementSelectorFunc 可通过以下两种方式定义：
返回 CSS 选择器字符串： 直接返回 CSS 选择器字符串，例如元素 ID (#valid-dom-id)、类名 (.valid-dom-class)，或更复杂的后代选择器 (#valid-dom-id .valid-dom-class)。SDK 将使用此选择器查找页面元素并渲染 UI。
返回异步函数回调： 若需在运行时动态创建或确定渲染元素，可返回一个 Promise，该 Promise 最终解析为一个 CSS 选择器字符串。这为复杂的动态 UI 场景提供了灵活性。
示例：
// 元素渲染回调的选择器原型
type ClientAttestationDOMSelector = () => string | Promise<string>

// 示例 1：使用元素 ID 指定元素（同步方式）
const tmpProviderSyncId: ClientAttestationDOMSelector = () => {
  return \\'#valid-dom-id\\'; // 返回元素ID选择器
};

// 示例 2：使用异步函数指定元素（动态创建元素）
const tmpProviderAsync: ClientAttestationDOMSelector = () => {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      const id = Math.random().toString(36).substring(2, 15);
      const iframe = document.createElement(\\'div\\');
      iframe.id = id;
      document.body.appendChild(iframe);
      resolve(`body > #${id}`); // 解析为选择器字符串
    }, 500);
  });
};

// 设置回调函数（选择其中一个示例进行设置）
// window.EOClientSecurityKit.setClientAttestationDOMSelectorProvider(tmpProviderSyncId);
// window.EOClientSecurityKit.setClientAttestationDOMSelectorProvider(tmpProviderAsync);

注意：
若页面内定义了指定渲染元素回调的选择器（选项一），将优先使用该选项。
若未通过 setClientAttestationDOMSelectorProvider 分配选择器回调函数，SDK 将查找页面中第一个 ID 为 eo-client-attestation 的 HTML 元素。找到后，该元素将用于渲染认证 UI。此方式提供了一种简单的约定，方便开发者预留认证 UI 显示区域。
示例：
<div id="eo-client-attestation"></div> <!-- 预留渲染区域的元素 -->
开发者可将此 div 元素放置在 HTML 页面合适位置，并根据需要定制样式，确保认证 UI 与页面整体设计风格一致。
当另外两种渲染选项均不存在时，EdgeOne SDK 将采取默认策略：在 HTML <body> 标签末尾动态创建一个新的 HTML 元素用于渲染认证 UI。
注意：
尽管此默认渲染方式能确保认证 UI 显示，但可能无法提供最佳用户体验。由于元素动态创建且位置固定在 <body> 末尾，其样式和布局可能与页面设计不协调，甚至可能被其他元素遮挡。因此，强烈建议开发者主动分配并指定专门用于渲染认证 UI 的元素（通过选项一 或选项二），以精确控制认证 UI 的显示位置、大小和样式，从而提供更优质的用户体验。

CORS 支持：配置自动认证范围（可选）

当页面集成第三方服务时，可能会遇到跨域资源共享 (CORS) 策略冲突。EdgeOne SDK 提供了灵活的机制来限制其请求拦截器的作用范围。通过合理配置自动认证范围，开发者可以有效管理 SDK 在复杂 Web 环境中的行为，避免与第三方服务的 CORS 策略产生冲突。


中国站
目录