设备指纹
接入指南

Android 集成指南

Android SDK 的安装、初始化、Token 获取与错误码说明

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 文件已被添加到 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.**{*;}

调用逻辑

  1. 在控制台注册并获取 AppID。
  2. 通过 AppID 获取 GeeGuardReceipt。

代码集成请参考下方示例。

示例代码

适用于 2.3.0 及以上版本。

应用启动后立即在 Geelab 控制台创建 appID 并配置服务区域

在管理后台创建 ID 时,submitServerUrl 必须与所选区域配置一致。

// Your AppID
const val appId = "123456789012345678901234567890ab"

// Specify the service URL if needed
// Global server, preconfigured in SDK
const val submitServerUrl = "https://riskct-global.geelabapi.com/api/v1/client_report"
// Europe
// const val submitServerUrl = "https://riskct-eu.geelabapi.com/api/v1/client_report"
// North America
// const val submitServerUrl = "https://riskct-na.geelabapi.com/api/v1/client_report"

class APP : Application() {
    override fun onCreate() {
        super.onCreate()
        // Register your AppID, using global server
        GeelabGuard.register(this, appId)
        // Using servers in other regions
        // GeelabGuard.register(this, appId, submitServerUrl)
    }
}

获取 GeeToken

使用 GeelabGuard SDK 对数据进行签名,并获取环境检测 GeeToken。

// Get the respondedGeeToken, which needs to be parsed on the server-side.
// This function callback is asynchronous.
fun getRespondedGeeToken(context: Context) {
    val data = "A unique transaction ID or credential to bind the GeeToken to the business context." 
    GeelabGuard.submitReceipt(context, data) { status ->
        if (status == 200) {
            //Submit along with business data, please obtain the final environmental identification result and fingerprint on the server side.
            // Please refer to the server-side documentation for the API parameters.
            text.postValue("RespondedGeeToken: ${receipt.respondedGeeToken}")
        } else {
            text.postValue("Status: $status")
        }
    }
}

错误码

异步获取方法 GeelabGuard.submitReceipt(Context, String, GeelabGuard.CallbackHandler) 可能返回以下错误码:

错误码说明
-200AppID 未注册,请在应用启动后注册 AppID。
-300网络错误,详情请参考错误对象 userInfo 中的信息。
-500服务响应格式异常,详情请查看 receipt.originalResponse
-501服务响应失败,详情请查看 receipt.originalResponse

查询 GeeToken 结果

respondedGeeTokenGeeToken 与业务数据一起提交到业务服务器,业务服务器再向 Geelab 设备指纹服务查询结果。更多信息请参考服务端文档。