tencent cloud

边缘安全加速平台 EO

动态与公告
产品动态
安全公告
产品公告
产品简介
产品概述
产品优势
应用场景
EdgeOne 与 CDN 等产品功能对比
使用限制
购买指南
试用套餐体验权益说明
免费版套餐使用说明
计费概述
计费项目
购买指引
续费指引
欠费与退款说明
套餐选型对比
关于“干净流量”计费说明
DDoS 防护容量说明
快速入门
选择业务场景
快速接入网站安全加速
通过 Pages 快速部署网站
域名服务与源站配置
域名服务
HTTPS 证书
源站配置
站点加速
概述
访问控制
智能加速
缓存配置
文件优化
网络优化
URL 重写
修改头部
修改应答内容
规则引擎
图片与视频处理
单连接下载限速
DDoS 与 Web 防护
概述
DDoS 防护
Web 防护
Bot 管理
API 资产识别(Beta)
边缘函数
概述
快速指引
操作指引
Runtime APIs
示例函数
实践教程
Pages
四层代理
概述
新建四层代理实例
修改四层代理实例配置
停用/删除四层代理实例
批量配置转发规则
获取客户端真实IP
数据分析与日志服务
日志服务
数据分析
告警服务
站点与计费管理
计费管理
站点管理
版本管理
通用策略
通用参考
配置语法
请求与响应行为
国家/地区及对应代码枚举
Terraform
Terraform 简介
安装和配置 Terraform
实践教程
自动预热/清除缓存
防盗刷/盗链实践
HTTPS 相关实践
加速优化
流量调度
数据分析与告警
第三方日志平台集成实践
对象存储类源站(例如:COS)配置实践
跨域响应配置
API 文档
History
Introduction
API Category
Making API Requests
Site APIs
Acceleration Domain Management APIs
Site Acceleration Configuration APIs
Edge Function APIs
Alias Domain APIs
Security Configuration APIs
Layer 4 Application Proxy APIs
Content Management APIs
Data Analysis APIs
Log Service APIs
Billing APIs
Certificate APIs
Origin Protection APIs
Load Balancing APIs
Diagnostic Tool APIs
Custom Response Page APIs
API Security APIs
DNS Record APIs
Content Identifier APIs
Legacy APIs
Ownership APIs
Image and Video Processing APIs
Multi-Channel Security Gateway APIs
Version Management APIs
Data Types
Error Codes
常见问题
产品特性相关问题
DNS 记录相关问题
域名配置相关问题
站点加速相关问题
数据与日志相关问题
安全防护相关问题
源站配置相关问题
排障指南
异常状态码参考
EdgeOne 4XX/5XX 状态码排障指南
520/524状态码排障指南
521/522 状态码排障指南
工具指南
相关协议
Service Level Agreement
源站防护启用特别约定
TEO 政策
隐私协议
数据处理和安全协议
联系我们
词汇表

Android 集成步骤

PDF
聚焦模式
字号
最后更新时间: 2025-11-18 16:05:42

概述

本节将详细阐述 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.gradledefaultConfig 中添加:
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() 方法随时获取当前有效的认证令牌。
注意:
每次调用 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;

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 渲染。

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈