边缘安全加速平台 EO Android 集成步骤

概述
本节将详细阐述 EdgeOne 客户端认证 SDK 在 Android 项目中的具体集成步骤，包括 SDK 的引入、权限配置、初始化、认证引擎启动、挑战处理以及令牌在 API 请求中的使用。
集成步骤
注意：
开始进行集成前，请确保您已阅读并理解 移动端集成概述，了解移动端的基本认证流程。
1. 将 EdgeOne SDK 添加到您的项目
将 EdgeOne 客户端认证 SDK 集成到您的 Android 项目中是首要步骤。您可以通过 Maven 引入 SDK。在您的 setting.gradle 或项目 build.gradle 中添加 Maven 源：
// setting.gradle 或项目 build.gradle
repositories {
    // 增加下面maven配置
    maven { url 'https://repo.maven.apache.org/maven2/' } // 示例Maven源，请替换为实际SDK提供的Maven源
}
在您的应用模块 build.gradle 中添加依赖：
// app/build.gradle
dependencies {
    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 { *; }
3. 初始化 SDK
在使用任何认证功能之前，您需要使用您的服务域和可选的日志级别初始化 EdgeOne SDK。此操作通常在您的 Application 类或应用启动时执行一次。
import com.tencent.cloud.clientattestation.TCBas;
import com.tencent.cloud.clientattestation.TCBasOptions;
﻿
public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // SDK初始化
        String baseUrl = "www.example.com"; // 设置为业务域名
        TCBas.init(getApplicationContext(), new TCBasOptions.Builder().baseUrl(baseUrl).build());
﻿
        // 可选：设置日志级别
        // TCBas.init(getApplicationContext(), new TCBasOptions.Builder()
        //     .baseUrl(baseUrl)
        //     .logLevel(LOG_LEVEL_DEBUG) // 可选，设置日志级别
        //     .build());
    }
}
参数说明：
baseUrl: 您的 EdgeOne 服务域名，例如 www.example.com。
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.tencent.cloud.clientattestation.ClientAttestation;
﻿
// 启动客户端认证引擎
ClientAttestation.getInstance().start();
注意： 认证引擎启动后，SDK 将准备好处理认证挑战和管理认证令牌。
5. 执行客户端认证挑战
认证挑战是获取认证令牌的关键步骤。此过程涉及获取挑战 ID 并将其传递给 SDK。SDK 会根据需要显示必要的 UI（例如在 WebView 中显示验证码）并计算认证令牌。这是通过 SDK 提供的 attestWithParams() 方法完成的。
import com.tencent.cloud.clientattestation.AttestCallback;
import com.tencent.cloud.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 可以是隐藏的。
reqTimeoutMillis: 可选参数，设置请求超时时间，单位：毫秒，默认 60 秒。
6. 在 API 请求中包含认证令牌
当您的 Android 应用向受 EdgeOne 保护的后端服务发起 API 请求时，务必在请求头中包含认证令牌。您可以通过调用 SDK 提供的 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;
﻿
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 嵌入式模式建议预留至少 300x230 像素空间，以获得最佳渲染效果和用户交互体验。
弹出式交互认证： 验证码界面在认证被调用时，以浮动窗口形式显示在设备屏幕上。与嵌入式认证类似，渲染窗口的大小、层叠顺序和对齐方式也需预设。弹出式认证的特点是，当屏幕视图小于特定阈值时，弹出式认证 GUI 会自动缩放以适应不同屏幕尺寸。例如，TC-CAPTCHA 弹出式模式的初始渲染块大小为 360x360 像素。
基于 JavaScript 的认证场景
某些认证器（例如，使用无感模式的 TC-CAPTCHA）需要 WebView 实例作为 JavaScript 运行时环境，主要用于执行加密工作量证明 (PoW) 挑战。在此场景下，WebView 实例仅提供 JavaScript 执行沙箱，无需可见地渲染任何 UI。因此，传入的 WebView 实例无需可见，SDK 也不会将其用于 UI 渲染。
Android 集成步骤

本页目录：

概述

集成步骤

1. 将 EdgeOne SDK 添加到您的项目

2. 配置 `AndroidManifest.xml` 权限

3. 初始化 SDK

4. 启动认证引擎

5. 执行客户端认证挑战

6. 在 API 请求中包含认证令牌

7. 处理服务器响应和挑战

8. （可选）使用 `WebView` 进行交互式认证（和 JS 认证）

交互式认证场景

基于 JavaScript 的认证场景
