一、集成步骤
注意：开始进行集成前，请确保你已阅读并理解 移动端集成概述，了解移动端的基本认证流程。
二、1. 将 EdgeOne SDK 添加到你的项目
将 EdgeOne 客户端认证 SDK 集成到你的 Android 项目中是首要步骤。你可以通过 Maven 引入 SDK。在你的 setting.gradle 或项目 build.gradle 中添加 Maven 源：
// setting.gradle 或项目 build.gradlerepositories { // 增加下面maven配置 maven { url 'https://repo.maven.com/' } // 示例Maven源，请替换为实际SDK提供的Maven源}
在你的应用模块 build.gradle 中添加依赖：
// app/build.gradledependencies { implementation 'com.tencent.cloud:clientattestation:latest.release'}
三、2. 配置 AndroidManifest.xml 权限
SDK 在执行认证过程时需要基本的网络访问权限。请在你的项目 AndroidManifest.xml 文件中添加以下权限声明，以确保 SDK 能够正常进行网络通信：
<uses-permission android:name="android.permission.INTERNET" /><uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
同时，为了支持 SDK 内部的某些原生库，你可能需要配置支持的 CPU 架构。在 app/build.gradle 的 defaultConfig 中添加：
android { defaultConfig { ndk { abiFilters "armeabi-v7a", "arm64-v8a" // 可选 armeabi-v7a 或 arm64-v8a } }}
如果你的项目使用了 ProGuard 进行代码混淆，请在你的 ProGuard 配置文件（通常是 proguard-rules.pro）中添加以下混淆规则，以防止 SDK 内部类被混淆：
-keep class com.**.TNative$aa { public *; }-keep class com.**.TNative$aa$bb { public *; }-keep class com.**.TNative$bb { *; }-keep class com.**.TNative$bb$I { *; }-keep class com.tcbas.**{*;}
四、3. 初始化 SDK
在使用任何认证功能之前，你需要使用你的服务域和可选的日志级别初始化 EdgeOne SDK。此操作通常在你的 Application 类或应用启动时执行一次。
import com.tcbas.common.framework.TCBas;import com.tcbas.common.framework.TCBasConfig;public class MyApplication extends Application { @Override public void onCreate() { super.onCreate(); // SDK初始化 String baseUrl = "www.example.com"; // 设置为业务域名 TCBas.init(getApplicationContext(), new TCBasConfig.Builder().baseUrl(baseUrl).build()); // 可选：设置日志级别 // TCBas.init(getApplicationContext(), new TCBasConfig.Builder() // .baseUrl(baseUrl) // .logLevel(LOG_LEVEL_DEBUG) // 可选，设置日志级别 // .build()); // 可选：设置AndroidId // TCBas.init(getApplicationContext(), new TCBasConfig.Builder() // .baseUrl(baseUrl) // .logLevel(LOG_LEVEL_DEBUG) // 可选，设置日志级别 // .extraDataProvider(new ExtraDataProvider(){ // @Override // public String getAndroidId() { // return super.getAndroidId(); // } // }) // .build()); }}
参数说明：
·baseUrl: 你的 EdgeOne 服务域名，例如 www.example.com。
·extraDataProvider: 可选参数，提供AndroidId，提升风险识别能力。
·logLevel: 可选参数，用于控制 SDK 的日志输出级别。可选值包括：
·LOG_LEVEL_NONE: 关闭日志（默认）
·LOG_LEVEL_DEBUG: 打开 debug 以上级别日志
·LOG_LEVEL_INFO: 打开 info 以上级别日志
·LOG_LEVEL_WARN: 打开 warning 以上级别日志
·LOG_LEVEL_ERROR: 打开 error 以上级别日志
五、4. 启动认证引擎
SDK 初始化完成后，你需要启动客户端认证引擎，以便 SDK 能够开始获取和管理认证令牌。此操作会启动 SDK 内部必要的后台进程。
import com.tc.eo.clientattestation.ClientAttestation;// 启动客户端认证引擎ClientAttestation.getInstance().start();
注意： 认证引擎启动后，SDK 将准备好处理认证挑战和管理认证令牌。
六、5. 执行客户端认证挑战
认证挑战是获取认证令牌的关键步骤。此过程涉及获取挑战 ID 并将其传递给 SDK。SDK 会根据需要显示必要的 UI（例如在 WebView 中显示验证码）并计算认证令牌。这是通过 SDK 提供的 attestWithParams() 方法完成的。
import com.tc.eo.clientattestation.ClientAttestation;import com.tc.eo.clientattestation.AttestCallback;import com.tc.eo.clientattestation.AttestParams;import android.webkit.WebView;// attestId// 主动发起挑战时从控制台获取// 被动发起挑战时从http返回的header字段中的‘EO-Attest-Challenge’获取String attestId = "your-attestId";AttestParams params = new AttestParams.Builder() .attestId(attestId) .webView(yourWebViewInstance) // 验证码界面显示使用的WebView，如果不需要验证码则不用设置此参数 .reqTimeoutMillis(60000) // 可选，请求超时时间，单位：毫秒，默认60秒 .build();ClientAttestation.getInstance().attestWithParams(params, new AttestCallback() { @Override public void onSuccess(String token) { // 返回风险票据，把票据放在http请求中的header字段‘EO-Attest-Token’ // 例如：你可以在这里重新发送之前失败的请求，并带上新的token } @Override public void onError(int errorCode, String msg) { // 错误信息回调 // errorCode: 错误码 // msg: 错误信息 }});
参数说明：
·attestId: 配置挑战 ID，从控制台获取或请求结果返回。
·webView: 可选参数，一个 WebView 实例。当认证器需要用户交互（如验证码）时，必须提供此参数。如果不需要 UI 交互，WebView 可以是隐藏的。
·captchaDisplayType: 可选参数，交互式验证码UI的显示模式。弹出全屏框显示时使用CaptchaDisplayType.POPUP，在页面内嵌显示使用CaptchaDisplayType.FULL，默认值：CaptchaDisplayType.POPUP。
·reqTimeoutMillis: 可选参数，设置请求超时时间，单位：毫秒，默认 60000 毫秒。
七、6. 在 API 请求中包含认证令牌
当你的 Android 应用向受 EdgeOne 保护的后端服务发起 API 请求时，务必在请求头中包含认证令牌。你可以通过调用 SDK 提供的 getAttestationToken() 方法随时获取当前有效的认证令牌。
注意：每次调用 attestWithParams() 成功后，SDK 都会生成或更新认证令牌。在将令牌附加到请求头之前，务必再次调用 getAttestationToken() 获取最新的令牌，每次需要使用令牌数据时，请重新获取新的令牌数据。请勿保存或重复使用 getAttestationToken() 返回的令牌数据。
// 获取客户端认证票据String attestToken = ClientAttestation.getInstance().getAttestationToken();// 示例：将令牌添加到你的网络请求头中// 假设你正在使用 OkHttp 或其他网络库if (attestToken != null) { // OkHttp 示例 // Request originalRequest = new Request.Builder() // .url("https://your-backend-api.com/data") // .build(); // Request.Builder requestBuilder = originalRequest.newBuilder(); // requestBuilder.header("EO-Attest-Token", attestToken); // Request request = requestBuilder.build(); // // 继续发送请求}
重要提示： 确保在每个需要认证的 API 请求中都包含此令牌。SDK 会自动管理令牌的生命周期，你只需在发送请求前获取最新令牌即可。
八、7. 处理服务器响应和挑战
当你的后端服务（受 EdgeOne 保护）收到客户端请求时，会检查请求中是否包含有效的认证令牌。如果请求需要认证但未携带有效令牌，服务器将返回 HTTP 428 状态码，指示客户端需要进行额外认证。这是 Android 客户端集成中需要开发者主动适配的关键环节。
你的 Android 应用需要实现一个机制来捕获并处理这些 HTTP 428 响应。具体处理流程参见 重新获取认证令牌，或续期已过期认证令牌（处理 HTTP 428 挑战）
以下是一个简化的处理 428 挑战的示例（以 OkHttp 为例）：
import okhttp3.Call;import okhttp3.Callback;import okhttp3.Headers;import okhttp3.OkHttpClient;import okhttp3.Request;import okhttp3.Response;import java.io.IOException;import android.webkit.WebView;import com.tc.eo.clientattestation.ClientAttestation;import com.tc.eo.clientattestation.AttestCallback;import com.tc.eo.clientattestation.AttestParams;public class ApiClient { private OkHttpClient client = new OkHttpClient(); private WebView webViewInstance; // 假设你有一个WebView实例 public ApiClient(WebView webView) { this.webViewInstance = webView; } public void makeProtectedRequest(String url) { Request request = new Request.Builder() .url(url) .header("EO-Attest-Token", ClientAttestation.getInstance().getAttestationToken()) .build(); client.newCall(request).enqueue(new Callback() { @Override public void onFailure(Call call, IOException e) { // 处理网络请求失败 e.printStackTrace(); } @Override public void onResponse(Call call, Response response) throws IOException { if (response.code() == 428) { Headers headers = response.headers(); String challengeId = headers.get("EO-Attest-Challenge"); if (challengeId != null) { // 收到 428 挑战，执行认证 AttestParams params = new AttestParams.Builder() .attestId(challengeId) .webView(webViewInstance) // 传入WebView实例 .build(); ClientAttestation.getInstance().attestWithParams(params, new AttestCallback() { @Override public void onSuccess(String token) { // 认证成功，重新发送请求 makeProtectedRequest(url); // 重新发起原始请求 } @Override public void onError(int errorCode, String msg) { // 认证失败 System.err.println("认证失败: " + msg); } }); } else { System.err.println("428 响应中未找到 EO-Attest-Challenge 头"); } } else if (response.isSuccessful()) { // 请求成功，处理业务数据 System.out.println("请求成功: " + response.body().string()); } else { // 处理其他 HTTP 错误 System.err.println("请求失败: " + response.code() + " " + response.message()); } } }); }}
九、8. （可选）使用 WebView 进行交互式认证（和 JS 认证）
在一些客户端认证场景中，认证器可能需要用户交互（如：交互式验证码）或执行计算密集型任务（如：加密工作量证明）。此时，EdgeOne SDK 需要特定的运行环境支持。在移动端平台上，WebView （Android 平台）是实现这些功能的关键组件。
当认证器需要渲染交互式验证码 (CAPTCHA) 或运行基于 JavaScript 的加密工作量证明 (Proof-of-Work) 挑战时，SDK 要求在调用 attestWithParams() 方法时提供一个 WebView 实例。这意味着开发者需在应用中预先分配 WebView 实例，并在调用认证 API 时将其作为参数传递给 SDK。
十、交互式认证场景
部分认证器（例如，使用嵌入式或弹出式交互设置的 TC-CAPTCHA）需要 WebView 实例来渲染其交互界面。该 WebView 实例将在应用内部显示验证码页面，因此需要预先设置以确保正确显示。
·嵌入式交互认证： 验证码界面以固定区块形式显示在设备屏幕上。为确保 UI 正确显示且不影响用户体验，开发者必须预设渲染窗口的大小、层叠顺序和对齐方式。请注意，嵌入式认证 GUI 不会随屏幕视图缩放。例如，TC-CAPTCHA 嵌入式模式建议预留至少 300×230 像素空间，以获得最佳渲染效果和用户交互体验。
·弹出式交互认证： 验证码界面在认证被调用时，以浮动窗口形式显示在设备屏幕上。与嵌入式认证类似，渲染窗口的大小、层叠顺序和对齐方式也需预设。弹出式认证的特点是，当屏幕视图小于特定阈值时，弹出式认证 GUI 会自动缩放以适应不同屏幕尺寸。例如，TC-CAPTCHA 弹出式模式的初始渲染块大小为 360×360 像素。
十一、基于 JavaScript 的认证场景
某些认证器（例如，使用无感模式的 TC-CAPTCHA）需要 WebView 实例作为 JavaScript 运行时环境，主要用于执行加密工作量证明 (PoW) 挑战。在此场景下，WebView 实例仅提供 JavaScript 执行沙箱，无需可见地渲染任何 UI。因此，传入的 WebView 实例无需可见，SDK 也不会将其用于 UI 渲染。