设备指纹
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.**{*;}

调用逻辑

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

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

示例代码

适用于 2.3.0 及以上版本的接入方式

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

创建 ID 时,submitServerUrl 必须与管理后台中的区域设置相对应。

// 后台获取的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) 可能返回以下错误码:

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

查询 GeeToken 结果

respondedGeeTokenGeeToken 随业务数据一同提交到业务服务端,业务服务端再向 Geelab 设备指纹服务查询结果。更多详情请参考服务端 API