MOBILE
Android
使用 Geelab 设备指纹 v2 Android SDK 完成原生 Android 接入
资源与概述
Geelab Android SDK 面向需要集成 Android 原生客户端的开发者提供。
| 项目 | 说明 |
|---|---|
| 产品名称 | Geelab 设备指纹 |
| 最新版本 (JS) | v2.7.4 |
| 最新发布日期 | 2026/4/22 |
| 主要功能 | 设备指纹采集 300 多项弱特征因子数据,并通过关系图谱和三维验证模型识别虚拟化、自动化和定制化设备,提供实时风险标签和状态。 |
环境与要求
| 项目 | 资源 |
|---|---|
| 开发对象 | Android 5.0+ (minSdk 21) |
| 开发环境 | Android Studio 2022.2.1+ (AGP 8+) |
| 编译工具 | Gradle(如使用 ant 编译,请解压并从包中提取 jar 和资源文件) |
| 系统依赖 | 无 |
| SDK 第三方依赖 | 无 |
安装
获取 SDK
请联系您的客户经理获取 SDK。
导入 SDK
从 zip 包中取出 .aar 文件(例如 geelabguard_android_vx.y.z_date.aar),并将其拖入项目的 libs 文件夹。将 .aar 文件拖入 libs 文件夹后,请确认该 .aar 文件已添加到 Library。同时需要在项目的 build.gradle 文件中添加以下代码:
repositories {
flatDir {
dirs 'libs'
}
}并且需要手动将 aar 包添加为依赖:
implementation(name: 'geelabguard_android_vx.y.z_date', ext: 'aar')添加权限声明
<!--必需 - 默认值为 apply-->
<uses-permission android:name="android.permission.INTERNET" />混淆规则配置
Geelab SDK 已完成混淆处理。集成时请添加以下混淆规则,且不要对 SDK 再次进行混淆。
-dontwarn tech.geelab.core.**
-keep class tech.geelab.core.**{*;}调用逻辑
- 在控制台注册并获取 AppID。
- 通过 AppID 获取 GeelabGuardReceipt。
代码集成请参考下方示例代码
示例代码
适用于 2.3.0 及以上版本的接入方式
应用启动后立即注册在 Geelab 控制台创建的 appID 并配置服务区域
创建 ID 时,
submitServerUrl必须与管理后台中的区域设置相对应。
| 区域 | submitServerUrl |
|---|---|
| 🌏 全球 | https://riskct-global.geelabapi.com/api/v2/client_report |
| 🇪🇺 欧洲 | https://riskct-eu.geelabapi.com/api/v2/client_report |
| 🇺🇸 北美 | https://riskct-na.geelabapi.com/api/v2/client_report |
// 后台获取的public_key
const val appId = "123456789012345678901234567890ab"
// 如有需要,可指定服务 URL
// 全球服务,SDK 已预配置
const val submitServerUrl = "https://riskct-global.geelabapi.com/api/v2/client_report"
// 欧洲
// const val submitServerUrl = "https://riskct-eu.geelabapi.com/api/v2/client_report"
// 北美
// const val submitServerUrl = "https://riskct-na.geelabapi.com/api/v2/client_report"
class APP : Application() {
override fun onCreate() {
super.onCreate()
// 注册您的 AppID,使用全球服务
GeelabGuard.register(this, appId)
// 使用其他区域的服务
// GeelabGuard.register(this, appId, submitServerUrl)
}
}获取 GeeToken
使用 GeelabGuard SDK 对数据进行签名,并获取环境检测 GeeToken。
// 直接获取 GeeToken,需要在服务端解析结果
fun getGeeToken(context: Context) {
thread {
val data = "用于将 GeeToken 绑定到业务上下文的唯一交易 ID 或凭证。"
val receipt = Geelab.fetchReceipt(context, data)
if (receipt != null) {
// 随业务数据一同提交,请在服务端获取最终环境识别结果和指纹。
// API 参数请参考服务端文档。
Log.i("GeeToken: ${receipt.geeToken}")
} else {
Log.w("无法获取 GeelabGuardReceipt,请检查是否已通过 GeelabGuard.register(appId) 注册 AppID。")
}
}
}
// 获取 respondedGeeToken,需要在服务端解析。
// 此函数回调为异步回调。
fun getRespondedGeeToken(context: Context) {
val data = "用于将 GeeToken 绑定到业务上下文的唯一交易 ID 或凭证。"
GeelabGuard.submitReceipt(context, data) { status ->
if (status == 200) {
// 随业务数据一同提交,请在服务端获取最终环境识别结果和指纹。
// API 参数请参考服务端文档。
text.postValue("RespondedGeeToken: ${receipt.respondedGeeToken}")
} else {
text.postValue("Status: $status")
}
}
GeelabGuard.submitReceipt(context, data) { status, receipt ->
when (status) {
// SDK 提交成功, 可以正常提交 respondedGeeToken 查询结果
200 -> text.postValue("RespondedGeeToken: ${receipt.respondedGeeToken}")
// 仅当给 SDK 传入的 appId 或 Context 为空时会触发, 请检查传参是否有效
-200 -> text.value = "Invalid appId or Context os null"
// 服务器响应失败, 其中 -300 为网络错误, -500 为服务响应格式异常, -501 为服务响应失败, 详情请查看服务端原始返回信息 receipt.originalResponse
// TODO: 此时可降级使用 receipt.geeToken (geeToken 长度约为 4000, respondedGeeToken 长度约为 1000) 进行查询
-300, -500, -501 -> {
// 服务端响应 body 原文
text.value = "${receipt.originalResponse}"
// 可以降级提交 geeToken 进行查询
Log.e("GeeLabGuard SubmitReceipt", receipt.geeToken)
}
// 暂无其他错误码
else -> throw IllegalStateException("Unexpected error code")
}
}错误码
异步获取方法 GeelabGuard.submitReceipt(Context, String, GeelabGuard.CallbackHandler) 可能返回以下错误码:
| 错误码 | 说明 |
|---|---|
| -200 | AppID 未注册,请在应用启动后注册 AppID |
| -300 | 网络错误,请参考 error 对象 userInfo 中的信息获取详情 |
| -500 | 服务响应格式异常,请查看 receipt.originalResponse 获取详情 |
| -501 | 服务响应失败,请查看 receipt.originalResponse 获取详情 |
查询 GeeToken 结果
将 respondedGeeToken 或 GeeToken 随业务数据一同提交到业务服务端,业务服务端再向 Geelab 设备指纹服务查询结果。更多详情请参考服务端 API。