顶象设备指纹（UNIFYID®）接入文档 原文标题：设备指纹 - 顶象文档中心

顶象

风控

人工智能

移动安全

顶象设备指纹（UNIFYID®）介绍

一、快速入门指南

1. 产品简介

顶象设备指纹通过用户上网设备的硬件、网络、环境等特征信息生成设备的唯一标识，覆盖安卓、iOS、Web/H5、公众号、小程序，可有效侦测模拟器、刷机改机、root越狱、劫持注入等风险，配合顶象风控系统使用，可有效对抗设备伪造、自动注册、羊毛党等恶意行为。

2. 名词解释

➡️ ➡️ ➡️ 开发者请注意

3. 交互流程

• 客户端接入，业务客户端需要集成顶象指纹客户端SDK，包括安卓，iOS，H5，小程序等；通过顶象客户端SDK可以获取到设备指纹token（注：token不是设备指纹）。

• 业务接口扩展，业务客户端在需要设备指纹token的时候，可以通过相应的api获取到。业务接口需要把前端拿到的指纹token一并传入后台。

• 后台接入，顶象提供后端SDK来查询设备详细信息，SDK涵盖Java，PHP等。

重要：因终端用户的设备网络环境和设备版本等因素，设备指纹采集率并不能一定达到100%，可能会存在极少部分未能正常采集到的情况。所以在集成指纹服务的时候，请尽量避免对指纹信息强依赖。

4. FAQ及版本记录

点击查看FAQ (https://www.dingxiang-inc.com/docs/preview/detail/const-id-faq)

二、前端接入

支持Web接入，支持IE8+、Chrome、Firefox、360浏览器、QQ浏览器等主流浏览器及Android、iOS上的内嵌Webview。引用JS参见Web接入章节

支持Android接入，获取SDK并接入，参见Android接入章节

支持iOS接入，获取SDK并接入，参见iOS接入章节

支持Harmony-Next接入，获取SDK并接入，参见harmony接入章节

Web接入

第一步：引入

SaaS客户在页面 HTML 中引入 const-id.js，代码形如：

<script src="https://cdn.dingxiang-inc.com/ctu-group/constid-js/index.js"></script>

因SaaS js文件会定期更新，为避免js失效影响您的使用，请不要将js下载到本地服务器上引入

私有化客户引入可下载使用私有化版本，下载地址：constid-js-private，对应ctu-constid服务版本5.4.+

第二步：生成并使用

页面加载后，初始化设备指纹，需要在 JavaScript 中调用 _dx.ConstID(options, callback) 方法获取设备指纹token，代码形如：

var options = {
 appId: '【这里填写 AppID】', // 唯一标识，必填
 server: 'https://constid.dingxiang-inc.com/udid/c1', // constId web端服务接口
 userId: '【这里填写 userID】' // 用户标识，可选
};
_dx.ConstID(options, function (err, token) {
 if (err) {
 // console.log('error: ' + err);
 return;
 }
 // console.log('const-id token is ' + token);
});

_dx.ConstID(options).then(function(token) {
 console.log(token)
}).catch(function(err) {
 console.log(err)
})

options 字段说明

PC浏览器兼容

移动端浏览器兼容

Android接入

一、 环境要求

若您需要额外的支持范围，请联系顶象技术以获取支持。

目前（2023-02-03）， android 5.0及以上占比为99.3%。

早期Android版本无法支持全部CPU架构（e.g. Android 4.0只支持armeabi）。

二、集成Android SDK

2.1 Android 合规指南

在集成顶象设备指纹(风控)SDK前，请完整、详细阅读该Android合规指南

顶象RISK Android SDK合规指南

2.1.1 Android SDK版本说明

2.1.2 Android SDK权限调用合规要求

2.1.3 初始化要求

Android SDK使用前必须调用先RiskSdk.setupInstance，setupInstance主要用于数据/环境初始化，一般在Application的onCreate下调用：

> RiskSdk.java
/**
* 初始化参数，环境
* @param context
* @return
*/
public static boolean setupInstance(Context context)

import com.dx.mobile.risk.RiskSdk;
public class App extends Application {
 public static RiskSdk riskSdk;
 @Override
 public void onCreate() {
 super.onCreate();
 riskSdk = RiskSdk.setupInstance(this);
 }
}

2.1.4 设置Risk权限（隐私合规）

在采集时，设置RiskApp所需权限，避免隐私合规等问题，详情请查看 3.2 隐私采集白名单。

> RiskApp.java
/**
 * 设置允许采集的隐私列表
 *
 * @param PrivacyFlag privacyFlag
 * @throws DXRiskErrorException
 * @see RiskSdk#setAllowPrivacyList(long)
 */
void setAllowPrivacyList(PrivacyFlag privacyFlag) throws DXRiskErrorException;

import com.dx.mobile.risk.PrivacyFlag;
import com.dx.mobile.risk.RiskApp;
public class MainActivity extends Activity {
 @Override
 protected void onCreate(Bundle savedInstanceState) {
 super.onCreate(savedInstanceState);
 RiskApp app = App.riskSdk.getRiskApp(APPID);
 //默认为PrivacyFlag.DEFAULT,涉及隐私的采集项均不采集
 app.setAllowPrivacyList(PrivacyFlag.ALL);
 }
}

2.1.5 最小化使用

同步指纹的整个过程由于是耗时操作，必须要在子线程上执行

import com.dx.mobile.risk.PrivacyFlag;
import com.dx.mobile.risk.RiskApp;
import com.dx.mobile.risk.RiskSdk;
public class MainActivity extends Activity {
 
 // 开通服务后可在应用管理菜单中获取；私有化版本请填写私有化appId
 private static final String APPID = "test";
 @Override
 protected void onCreate(Bundle savedInstanceState) {
 super.onCreate(savedInstanceState);
 RiskApp app = App.riskSdk.getRiskApp(APPID);
 app.setAllowPrivacyList(PrivacyFlag.ALL);
 Map<String, String> params = new HashMap<>();
 // 这里请填写对应的服务端url，注意SAAS和私有化的区别
 params.put(RiskSdk.KEY_URL, "https://constid.dingxiang-inc.com/udid/m1");
 // 设置请求方法超时时长ms，不设置默认为5000ms
 params.put(RiskSdk.KEY_TIMEOUT_MS, "5000");
 //此配置关闭SDK缓存，表示每次调用接口都是强制采集信息
 params.put("PRIVATE_CLEAR_TOKEN", "true");
 app.init(params);
 
 new Thread() {
 @Override
 public void run() {
 final String token = app.getToken();
 //token为40位的字符串
 }
 }
 
 }
}

2.1.6 Android SDK隐私政策披露

SDK名称：顶象设备指纹(风控)Risk SDK(Android)

收集个人信息类型：【必选】设备版本、【必选】系统版本、【必选】生成ID、【必选】手机样式、【必选】手机名、【必选】APP应用包名、【必选】APP应用名、【必选】APP应用版本、【必选】移动设备运营商名称、【必选】国家代码、【必选】运营商代码、【可选】iccid、【可选】bssid、【可选】MAC地址、【可选】IMSI、【可选】IMEI、【可选】IP地址、【可选】AndroidID、【可选】蓝牙信息、【可选】GPS信息

隐私权政策链接：https://www.dingxiang-inc.com/about/privacy-mobile-risk

注：若收集个人信息类型中标记为可选的未在业务场景中使用，请不要声明

2.1.7 用户授权同意的建议方式

若您使用了设备指纹（风控）SDK的部分功能,并使用了电话权限或地理位置权限的声明，那您还需要对以下场景做特殊处理

您如果使用了电话权限，需要对客户进行双弹窗或蒙层提示，该业务场景使用电话权限并采集IMEI\IMSI等电话相关的个人信息

如果用户选择不同意该权限的申请，不应阻塞设备指纹（Risk）业务的进行，顶象Risk SDK在用户不同意该权限后，也不会采集相关权限的个人信息

您如果使用了地理位置权限，需要对客户进行双弹窗或蒙层提示，该业务场景使用地理位置权限并采集经纬度\方位角\高度等地理位置相关的个人信息

如果用户选择不同意该权限的申请，不应阻塞设备指纹（Risk）业务的进行，顶象Risk SDK用户不同意该权限后，也不会采集相关权限的个人信息

2.2 下载Android SDK

2.3 Android Studio 集成

2.3.1 把aar文件放到相应模块的libs目录下

.
├── app
│ ├── build.gradle
│ ├── libs
│ │ └── dx-risk-vx_x_xxr_xxxxxxxx.aar
│ ├── proguard-rules.pro
│ └── src
│ └── main
├── build.gradle
├── gradle
├── gradle.properties
├── gradlew
├── gradlew.bat
└── settings.gradle

2.3.2 在该Module的build.gradle中如下配置:

android {
 packagingOptions {
 doNotStrip "**/lib*Risk*.so"
 }
}
dependencies {
 implementation fileTree(dir: 'libs', include: ['*.aar'])
}

2.3.3（可选）添加SDK所需权限

<uses-permission android:name="android.permission.INTERNET"/>

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>
<uses-permission android:name="android.permission.BLUETOOTH"/>

2.3.4 Proguard混淆配置

-dontskipnonpubliclibraryclassmembers
-keepattributes *Annotation*,EnclosingMethod
-dontwarn com.dx.mobile.**
-dontwarn *.com.dx.mobile.**
-dontwarn *.com.mobile.strenc.**
-keep class com.dx.mobile.risk.**{*;}
-keep class com.security.inner.**{*;}
-keep class *.com.dx.mobile.**{*;}
-keep class *.com.mobile.strenc.**{*;}

2.3.5 API 6.0或以上动态权限申请说明

android.permission.WRITE_EXTERNAL_STORAGE
android.permission.READ_EXTERNAL_STORAGE
android.permission.READ_PHONE_STATE
android.permission.ACCESS_COARSE_LOCATION
android.permission.ACCESS_FINE_LOCATION

public static RiskSdk riskSdk;
protected void onCreate(Bundle savedInstanceState) {
 super.onCreate(savedInstanceState);
 setContentView(R.layout.activity_demo);
 // 该设置请参考下方 3.1章节中 隐私采集白名单
 riskSdk = RiskSdk.setupInstance(this);
 RiskApp app = riskSdk.getRiskApp(APPID);
 app.setAllowPrivacyList(PrivacyFlag.ALL);
 // API 23或以上的动态申请权限
 if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
 String[] permissionArray = {
 "android.permission.ACCESS_COARSE_LOCATION",
 "android.permission.ACCESS_FINE_LOCATION",
 "android.permission.ACCESS_BACKGROUND_LOCATION",
 "android.permission.WRITE_EXTERNAL_STORAGE",
 "android.permission.READ_EXTERNAL_STORAGE",
 "android.permission.READ_PHONE_STATE",
 };
 this.requestPermissions(permissionArray, 1);
 }
}
@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
 super.onRequestPermissionsResult(requestCode, permissions, grantResults);
 // start getToken
 new Thread(new Runnable() {
 @Override
 public void run() {
 HashMap<String, String> params = new HashMap<String, String>();
 params.put(RiskSdk.KEY_URL,"XXX");
 app.init(params);
 String token = app.getToken();
 }
 }).start();
}

三、接口使用说明

3.1 方法和参数说明

3.1.1 功能描述

采集端的设备指纹信息，上传至风控后台，再由风控后台返回token。 该API为耗时操作，因此必须在子线程上调用，否则会抛异常。

3.1.2 方法说明

RiskSdk.java、RiskApp.java 该类是DxRisk SDK的风控组件接口，负责采集本地信息并返回用户前端token。

3.2 隐私采集白名单

自v6.1.18r开始，SDKsetup前，可以调用setAllowPrivacyList进行隐私采集白名单的设置，默认关闭所有涉及隐私规范红线的采集项 自v7.3.19r开始，即使设置了隐私白名单对隐私红线项目放行，隐私红线项目也仅会采集一次，避免超频采集带来的影响

public static void setAllowPrivacyList(long privacyFlag)

riskApp.setAllowPrivacyList(PrivacyFlag.ANDROID_ID); //只采集ANDROID_ID

//自定义列表模式
riskApp.setAllowPrivacyList(PrivacyFlag.X | PrivacyFlag.Y | ...); //表示既采集X又采集Y,X、Y表示具体某项采集的FLAG值，如下表

3.3 初始化setup

SDK使用前必须调用先setupInstance，setupInstance主要用于数据/环境初始化，一般在Application的onCreate下调用：

> RiskSdk.java
/**
* 初始化参数，环境
* @param context
* @return
*/
public static boolean setupInstance(Context context)

3.3.1 获取RiskApp

> RiskSdk.java
/**
 * 获取RiskApp
 *
 * @param appId
 * @return
 * @throws DXRiskErrorException
 */
public abstract RiskApp getRiskApp(String appId) throws DXRiskErrorException;

3.3.2 获取Token

> RiskApp.java
/**
 * 获取指纹token
 *
 * @param overrideConfig 可为null, 用于覆盖 {@link RiskApp#init(Map)} 的默认配置
 * @return 可能返回null
 * @throws DXRiskErrorException
 */
String getToken(Map<String, String> overrideConfig) throws DXRiskErrorException;

3.4 使用示例

3.4.1 初始化setup

建议Application.onCreate下调用

SDK初始化必须在主线程初始化，否则会有Crash风险。

@Override
public class App extends Application {
 public static RiskSdk riskSdk;
@Override
 public void onCreate() {
 super.onCreate();
 // 必须在主线程初始化
 riskSdk = RiskSdk.setupInstance(this);
 }
}

3.4.2 获取token

整个过程由于是耗时操作，必须要在子线程上执行，否则会crash

new Thread(){
 @Override
 public void run() {
 String APPID = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
 RiskApp app = App.riskSdk.getRiskApp(APPID);
 app.setAllowPrivacyList(PrivacyFlag.ALL);
 /* 私有化配置 */
 HashMap<String, String> params = new HashMap<String, String>();
 // 这里请填写对应的服务端url，注意SAAS和私有化的区别
 params.put(RiskSdk.KEY_URL, "https://constid.dingxiang-inc.com");
 // 设置请求方法超时时长ms，不设置默认为2000ms
 params.put(RiskSdk.KEY_TIMEOUT_MS, "2000");
 //此配置关闭SDK缓存，表示每次调用接口都是强制采集信息
 // params.put("PRIVATE_CLEAR_TOKEN", "true");
 // 开通服务后可在应用管理菜单中获取；私有化版本请填写私有化appId
 app.init(params);
 // 获取设备指纹token
 final String token = app.getToken();
 // TODO 把token通过Post请求，传到用户后端
 }
}.start();

3.5 异常说明

在获取token过程中，如果因为网络超时或者加解密失败，该接口有可能会返回为null，同时会输出tag为DXRISK的错误信息，具体描述如下：

DXRISK_REQUEST_NETWORK_ERR -1001 //网络链接失败
DXRISK_REQUEST_DECRYPT_ERR -1002 //数据解密错误
DXRISK_REQUEST_UNCOMPRESS_ERR -1003 //解压错误
DXRISK_REQUEST_RESPONSE_EMPTY_ERR -1004 //返回为空
DXRISK_REQUEST_DATA_PARSE_ERR -1005 //数据解析失败
DXRISK_REQUEST_DIRTY_DATA_ERR -1006 //脏数据
DXRISK_CONST_ID_EMPTY -1007 //constid为空

iOS接入

iOS SDK合规指南

在集成顶象设备指纹（Risk）iOS SDK前，请完整、详细阅读该iOS合规指南

一、顶象Risk iOS SDK合规指南

1.1 iOS SDK版本说明

1.2 iOS SDK权限调用合规要求

1.3 初始化要求

// 整个过程由于是耗时操作，必须要在子线程上执行，否则会阻塞UI。如果本身已经在非UI线程上执行，则不需要另开线程
 dispatch_queue_t dxrisk_queue = dispatch_queue_create("com.dingxiang.dxrisk", DISPATCH_QUEUE_CONCURRENT);
 dispatch_async(dxrisk_queue, ^{
 NSMutableDictionary *dic = [NSMutableDictionary dictionary];
 // 根据业务逻辑，填充自定义字段
 [dic setObject:@"123456" forKey:DXRiskManagerKeyUserId];
 // 如需设置海外服务器, 可选值请参考头文件字段
 [dic setObject:DXRiskManagerServiceAreaSoutheastAsia forKey:DXRiskManagerKeyServiceArea];
 // 如需自定义服务端URL，填充DXRiskManagerKeyURL字段（私有化部署的情况）
 // 如有需要则添加DXRiskManagerKeyBackup参数，Value固定为DXRiskManagerKeyBackupEnable
 // DXRiskManagerKeyBackupAppId参数可不填，参数为顶象备份数据库提供的备份Appid
 [dic setObject:@"http://xxxxxxx" forKey:DXRiskManagerKeyURL];
 // [dic setObject:DXRiskManagerKeyBackupEnable forKey:DXRiskManagerKeyBackup];
 [dic setObject:@"xxxxxxxxxxxxxxxxxxxx" forKey:DXRiskManagerKeyBackupAppId];
 // 此配置关闭SDK缓存，表示每次调用接口都强制采集信息
 // [dic setObject:@"true" forKey:@"PRIVATE_CLEAR_TOKEN"];
 // 获取token
 // 注意：token最好不要保存在某个局部变量或者字段，每次使用时，都通过API获取。
 BOOL isSuccess = [DXRiskManager setup];
 NSLog(@"setup success: %@" , isSuccess ? @"YES":@"NO");
 NSString *constID = [DXRiskManager getToken:@"xxxxxxxxxxxxxxxxxxxx" extendsParams:dic WithSid:nil];
 NSLog(@"constID: %@", constID);
 // TODO 把constid通过Post请求，传到业务后台。
 // 下面是模拟频繁调用的过程
 while(TRUE) {
 NSLog(@"constID: %@", [DXRiskManager getToken:@"xxxxxxxxxxxxxxxxxxxx" extendsParams:dic WithSid:nil]);
 [NSThread sleepForTimeInterval:.5];
 }
 });

1.4 最小化使用

dispatch_queue_t dxrisk_queue = dispatch_queue_create("com.dingxiang.dxrisk", DISPATCH_QUEUE_CONCURRENT);
 dispatch_async(dxrisk_queue, ^{
 NSMutableDictionary *dic = [NSMutableDictionary dictionary];
 [DXRiskManager setup];
 NSString *constID = [DXRiskManager getToken:@"appid" extendsParams:dic WithSid:nil];
 });

1.5 iOS SDK隐私政策披露

SDK名称：顶象设备指纹(风控)Risk SDK(IOS)

收集个人信息类型：【必选】设备版本、【必选】系统版本、【必选】生成ID、【必选】手机样式、【必选】手机名、【必选】APP应用包名、【必选】APP应用名、【必选】APP应用版本、【必选】移动设备运营商名称、【必选】国家代码、【必选】运营商代码、【可选】iccid、【可选】bssid、【可选】MAC地址、【可选】IMSI、【可选】IMEI、【可选】IP地址、【可选】蓝牙信息、【可选】GPS信息

隐私权政策链接：https://www.dingxiang-inc.com/about/privacy-mobile-risk

注：若收集个人信息类型中标记为可选的未在业务场景中使用，请不要声明

1.6 用户授权同意的建议方式

您如果使用了IDFA权限，需要对客户进行双弹窗或蒙层提示，该业务场景使用电话权限并采集IDFA相关的个人信息

如果用户选择不同意该权限的申请，不应阻塞设备指纹（Risk）业务的进行，顶象设备指纹(风控)SDK在用户不同意该权限后，也不会采集相关权限的个人信息

您如果使用了地理位置权限，需要对客户进行双弹窗或蒙层提示，该业务场景使用地理位置权限并采集经纬度\方位角\高度等地理位置相关的个人信息

如果用户选择不同意该权限的申请，不应阻塞设备指纹（Risk）业务的进行，顶象设备指纹(风控)SDK在用户不同意该权限后，也不会采集相关权限的个人信息

二、环境需求

三、集成iOS SDK

3.1 下载iOS SDK

• dx-risk-iOS-x.x.x-xxxxxxx目录 DXRisk sdk

• DXRisk.xcframework 不带idfa获取逻辑的Dynamic Library Framework

• DXRiskWithIDFA.xcframework 带idfa获取逻辑的Dynamic Library Framework

• DXRiskStatic.xcframework 不带idfa获取逻辑的Static Library Framework

• DXRiskStaticWithIDFA.xcframework 带idfa获取逻辑的Static Library Framework

3.2 将SDK接入Xcode

3.2.1 导入XCFramework

DXRisk.xcframework,DXRiskWithIDFA.xcframework,DXRiskStatic.xcframework,DXRiskStaticWithIDFA.xcframework`其中之一直接拖入工程目录中，或者右击总文件夹添加文件。

• 如果App中包含广告相关的功能，则选择DXRiskWithIDFA.xcframework 或者 DXRiskStaticWithIDFA.xcframework，该版本可以提供更精准的token

• 如果没有广告，获取idfa可能导致拒绝上架，此时请选择DXRisk.xcframework 或者 DXRiskStatic.xcframework

3.2.2 添加FrameWork到工程

若在项目中添加DXRisk.xcframework或者DXRiskWithIDFA.xcframework其中之一，选择Target -> General，在Frameworks,Libraries,and Embedded Content中，将DXRisk.xcframework或者DXRiskWithIDFA.xcframework 对应的 Embed 切换到Embed & Sign。如下图：

若在项目中添加DXRiskStatic.xcframework或者DXRiskStaticWithIDFA.xcframework其中之一，需要在Build Settings -> Other Linker Flags 设置 -ObjC 如下图：

3.2.4 权限注意

在iOS 12的环境最好在Capabilities->Access WiFi Information 进行开启操作，这样方便设备指纹数据采集。

四、接口使用说明

4.1 方法和参数说明

// 风控组件：DXRiskManager类
@interface DXRiskManager : NSObject
// 字符串常量
extern NSString* const DXRiskManagerKeyUserId;
extern NSString* const DXRiskManagerKeyEmail;
extern NSString* const DXRiskManagerKeyPhone;
extern NSString* const DXRiskManagerKeyUserExtend1;
extern NSString* const DXRiskManagerKeyUserExtend2;
extern NSString* const DXRiskManagerKeyURL;//私有化服务器地址
extern NSString* const DXRiskManagerKeyBackup;//私有化下使用，将数据备份到顶象服务器（开启为DXRiskManagerKeyBackupEnable 值）
extern NSString* const DXRiskManagerKeyBackupAppId; // 私有化下使用，指定数据备份到顶象服务器的AppId
extern NSString* const DXRiskManagerKeyDegradeNotify;//数据降级通知，若打开，服务端会有响应的降级统计
extern NSString* const DXRiskManagerKeyCountry;//国家地区设置，默认中国
extern NSString* const DXRiskManagerKeyDelayMsTime; //可填设置请求超时毫秒时间（默认值为 500 ，范围是：【100 ： 3000】）
// NoticeDegrade参数
/* The NoticeDegrade Value. This value only be used pair with key:DXRiskManagerKeyDegradeNotify to notify token degrade. */
extern NSString* const DXRiskManagerKeyDegradeNotifyEnable;
// Backup参数
/* The Backup Value. This value only be used pair with key:DXRiskManagerKeyBackup to set data backup. */
extern NSString* const DXRiskManagerKeyBackupEnable;
// Country参数
/* The Country Value. This value only be used pair with key:DXRiskManagerKeyCountry to set country. */
extern NSString* const DXRiskManagerCountryChina;
/* The Country Value. This value only be used pair with key:DXRiskManagerKeyCountry to set country. */
extern NSString* const DXRiskManagerCountryIndonesia;
/**
 DXRiskManager -- 初始化方法
 */
+ (BOOL)setup;
/**
 采集端的设备指纹信息，上传至风控后台，再由风控后台返回token。
 该API为耗时操作，因此必须在子线程上调用。
 @param extendsParams 业务方用户唯一标识，用户名，用户ID，Email等等，常用Key值可参考DXRiskManagerKeyUserId, DXRiskManagerKeyEmail等等
 @param appId appId
 @param sid 业务数据 hex
 @return token
 */
+ (NSString *)getToken:(NSString *)appId extendParams:(NSDictionary *)extendsParams WithSid:(NSString *)sid;;
@end

4.2 使用示例

// 整个过程由于是耗时操作，必须要在子线程上执行，否则会阻塞UI。如果本身已经在非UI线程上执行，则不需要另开线程
 dispatch_queue_t dxrisk_queue = dispatch_queue_create("com.dingxiang.dxrisk", DISPATCH_QUEUE_CONCURRENT);
 dispatch_async(dxrisk_queue, ^{
 NSMutableDictionary *dic = [NSMutableDictionary dictionary];
 // 根据业务逻辑，填充自定义字段
 [dic setObject:@"123456" forKey:DXRiskManagerKeyUserId];
 // 如需设置海外服务器, 可选值请参考头文件字段
 [dic setObject:DXRiskManagerServiceAreaSoutheastAsia forKey:DXRiskManagerKeyServiceArea];
 // 如需自定义服务端URL，填充DXRiskManagerKeyURL字段（私有化部署的情况）
 // 如有需要则添加DXRiskManagerKeyBackup参数，Value固定为DXRiskManagerKeyBackupEnable
 // DXRiskManagerKeyBackupAppId参数可不填，参数为顶象备份数据库提供的备份Appid
 [dic setObject:@"http://xxxxxxx" forKey:DXRiskManagerKeyURL];
 // [dic setObject:DXRiskManagerKeyBackupEnable forKey:DXRiskManagerKeyBackup];
 [dic setObject:@"xxxxxxxxxxxxxxxxxxxx" forKey:DXRiskManagerKeyBackupAppId];
 // 此配置关闭SDK缓存，表示每次调用接口都强制采集信息
 // [dic setObject:@"true" forKey:@"PRIVATE_CLEAR_TOKEN"];
 // 获取token
 // 注意：token最好不要保存在某个局部变量或者字段，每次使用时，都通过API获取。
 BOOL isSuccess = [DXRiskManager setup];
 NSLog(@"setup success: %@" , isSuccess ? @"YES":@"NO");
 NSString *constID = [DXRiskManager getToken:@"xxxxxxxxxxxxxxxxxxxx" extendsParams:dic WithSid:nil];
 NSLog(@"constID: %@", constID);
 // TODO 把constid通过Post请求，传到业务后台。
 // 下面是模拟频繁调用的过程
 while(TRUE) {
 NSLog(@"constID: %@", [DXRiskManager getToken:@"xxxxxxxxxxxxxxxxxxxx" extendsParams:dic WithSid:nil]);
 [NSThread sleepForTimeInterval:.5];
 }
 });

4.3 异常说明

在获取token过程中，如果因为网络超时或者加解密失败，该接口有可能会返回为null，同时会输出tag为DXRISK的错误信息，具体描述如下：

DXRISK_REQUEST_NETWORK_ERR -1001 //网络链接失败
DXRISK_REQUEST_DECRYPT_ERR -1002 //数据解密错误
DXRISK_REQUEST_UNCOMPRESS_ERR -1003 //解压错误
DXRISK_REQUEST_RESPONSE_EMPTY_ERR -1004 //返回为空
DXRISK_REQUEST_DATA_PARSE_ERR -1005 //数据解析失败
DXRISK_REQUEST_DIRTY_DATA_ERR -1006 //脏数据
DXRISK_CONST_ID_EMPTY -1007 //constid为空

Harmony-Next接入

一、 环境要求

若您需要额外的支持范围，请联系顶象技术以获取支持。

二、 集成Harmony-Next SDK

Harmony-Next合规指南

在集成顶象设备指纹(风控)SDK前，请完整、详细阅读该Harmony-Next合规指南

2.1 顶象RISK Harmony-Next SDK合规指南

2.1.1 Harmony-Next SDK版本说明

2.1.2 Harmony-Next SDK权限调用合规要求

2.1.3 初始化要求

初始化时必须调用setupInstance获取sdk对象实例，并传入App的应用上下文

import { RiskSdk,RiskApp } from '@dxms/risk'
let riskSdk: RiskSdk = await RiskSdk.setupInstance(getContext().getApplicationContext());

2.1.4 最小化使用

let map: HashMap<string, string> = new HashMap();
 map.set("PRIVATE_CLEAR_TOKEN", "clear")
 map.set(RiskSdk.KEY_URL, "");
 let riskSdk: RiskSdk = await RiskSdk.setupInstance(getContext().getApplicationContext());
 let riskApp: RiskApp = await riskSdk.getRiskApp("")
 riskApp.init(map)
 token = await riskApp.getToken();

2.1.5 Harmony-Next SDK隐私政策披露

SDK名称：顶象设备指纹(风控)Risk SDK(Harmony)

收集个人信息类型：【必选】设备版本、【必选】系统版本、【必选】生成ID、【必选】APP应用包名、【必选】APP应用名、【必选】APP应用版本

隐私权政策链接：https://www.dingxiang-inc.com/about/privacy-mobile-risk

注：若收集个人信息类型中标记为可选的未在业务场景中使用，请不要声明

2.1.6 用户授权同意的建议方式

设备指纹小程序合规指南

小程序合规指南说明

在集成顶象设备指纹(风控)小程序前，请完整、详细阅读该合规指南

一、小程序版本说明

二、设备指纹小程序权限调用合规要求

小程序设备指纹SDK网络权限继承自平台App，并未涉及需要用户特殊授权，遵循了平台App相关的隐私政策。

注：支付宝小程序官方并未对权限名称作出说明，故留空。

三、初始化要求

将对应小程序版本js下载到本地，引入小程序中即可使用

const ConstId = require('本地设备指纹js存放路径')

四、最小化使用

const ConstId = require('本地设备指纹js存放路径')
Page({
 onLoad: function () {
 new ConstId({
 appId: '',
 server: ''
 }, (e, id) => {
 })
 }
})

五、小程序隐私政策披露

SDK名称：顶象设备指纹小程序(风控)Risk 小程序

收集个人信息类型：【必选】设备版本、【必选】系统版本、【必选】手机样式、【可选】蓝牙信息、【可选】GPS信息

隐私权政策链接：https://www.dingxiang-inc.com/about/privacy-xcx-risk

注：若收集个人信息类型中标记为可选的未在业务场景中使用，请不要声明

六、用户授权同意的建议方式

您需要在小程序隐私政策文档中添加顶象设备指纹小程序（风控）SDK隐私披露相关内容

您如果使用了蓝牙权限，该业务场景使用蓝牙权限并采集蓝牙是否可用、在蓝牙模块生效期间所有搜索到的蓝牙设备等蓝牙相关的个人信息

如果用户选择不同意该权限的申请，不应阻塞风控业务的进行，顶象Risk SDK在用户不同意该权限后，也不会采集相关权限的个人信息

您如果使用了地理位置权限，该业务场景使用地理位置权限并采集经纬度等地理位置相关的个人信息

如果用户选择不同意该权限的申请，不应阻塞风控业务的进行，顶象Risk SDK用户不同意该权限后，也不会采集相关权限的个人信息

微信小程序接入

一、下载设备指纹js

私有化版本下载，对应ctu-constid服务版本5.4.+

二、获取密钥

未注册用户可在顶象官网进行账号注册，创建应用获取应用密钥AppID和AppSecret。

三、使用

const ConstId = require('本地设备指纹js存放路径')
Page({
 onLoad: function () {
 new ConstId({
 appId: '【这里填写在顶象官网申请到的 AppID】', // 唯一标识，必填
 server: 'https://host/udid/w1' // 服务接口地址，请注意私有化客户填写自有域名
 //excludeKeys: ['bluetoothDevices', 'gps', 'wifiList'] 取消蓝牙、及地理授权。默认开启蓝牙及地理位置授权
 }, (e, id) => {
 if (e) {
 console.log(e)
 return
 }
 console.log('constId:', id)
 })
 }
})

• SaaS用户在小程序后台配置业务域名https://constid.dingxiang-inc.com，私有化用户配置本地部署域名，测试阶段可以开启微信开发者工具右上角详情->本地设置->“不校验域名”。

支付宝小程序接入

一、下载设备指纹js

私有化版本下载，对应ctu-constid服务版本5.4.+

二、获取密钥

未注册用户可在顶象官网进行账号注册，创建应用获取应用密钥AppID和AppSecret。

三、使用

const ConstId = require('本地设备指纹js存放路径')
Page({
 onLoad: function () {
 new ConstId({
 appId: '【这里填写在顶象官网申请到的 AppID】', // 唯一标识，必填
 server: 'https://host/udid/w1' // 服务接口地址，请注意私有化客户填写自有域名
 }, (e, id) => {
 if (e) {
 console.log(e)
 return
 }
 console.log('constId:', id)
 })
 }
})

百度小程序接入

一、下载设备指纹js

私有化版本下载，对应ctu-constid服务版本5.4.+

二、获取密钥

未注册用户可在顶象官网进行账号注册，创建应用获取应用密钥AppID和AppSecret。

三、使用

const ConstId = require('本地设备指纹js存放路径')
Page({
 onLoad: function () {
 new ConstId({
 appId: '【这里填写在顶象官网申请到的 AppID】', // 唯一标识，必填
 server: 'https://host/udid/w1' // 服务接口地址，请注意私有化客户填写自有域名
 }, (e, id) => {
 if (e) {
 console.log(e)
 return
 }
 console.log('constId:', id)
 })
 }
})

抖音小程序接入

一、下载设备指纹js

私有化版本下载，对应ctu-constid服务版本5.4.+

二、获取密钥

未注册用户可在顶象官网进行账号注册，创建应用获取应用密钥AppID和AppSecret。

三、使用

const ConstId = require('本地设备指纹js存放路径')
Page({
 onLoad: function () {
 new ConstId({
 appId: '【这里填写在顶象官网申请到的 AppID】', // 唯一标识，必填
 server: 'https://host/udid/w1' // 服务接口地址，请注意私有化客户填写自有域名
 }, (e, id) => {
 if (e) {
 console.log(e)
 return
 }
 console.log('constId:', id)
 })
 }
})

uniapp接入

一、下载设备指纹js

私有化版本下载，对应ctu-constid服务版本5.4.+

二、获取密钥

未注册用户可在顶象官网进行账号注册，创建应用获取应用密钥AppID和AppSecret。

三、使用

const ConstId = require('本地设备指纹js存放路径')
export default{
 onLoad: function () {
 new ConstId({
 appId: '【这里填写在顶象官网申请到的 AppID】', // 唯一标识，必填
 server: 'https://host/udid/w1' // 服务接口地址，请注意私有化客户填写自有域名
 }, (e, id) => {
 if (e) {
 console.log(e)
 return
 }
 console.log('constId:', id)
 })
 }
}

三、后端接入

接口详细描述： 根据token,appId,sign三个参数获得设备信息

SDK接入方法说明

1 Java SDK接入

<dependency>
 <groupId>com.dingxiang-inc</groupId>
 <artifactId>ctu-client-sdk</artifactId>
 <version>2.6</version>
</dependency>

public class ConstantIdDemo {
 //顶象控制台，设备指纹菜单应用管理里面获取
 private static String appId = "0091a3xxxxxxxxxx557fac67b2f5afb";
 private static String appSecret = "e38dxxxxxxxxx6807c9e1edebaa2836";
 public static void main(String[] args) throws IOException {
 // 填写设备指纹域名或者url如：http://127.0.0.1:8080
 CtuConstidClient client = new CtuConstidClient("https://constid.dingxiang-inc.com", appId, appSecret);
 //设备指纹
 String result = client.getDeviceInfo("62c5013cel9o4xxxxxxxxxtTtKW5BwWtQq9u1f1");
 System.out.println(JSON.toJSON(result));
 }
}

2 PHP SDK接入

class Demo {
 // 根据实际情况填写
 const appKey = "你的AppID";
 // 根据实际情况填写
 const appSecret = "你的AppSecret";
 // 根据实际情况填写
 const token = "SDK里面获取到的token";
}
// 根据token获取设备详细信息工具类
$requestHandle = new DeviceFingerprintHandle();
// 设置请求超时时间。因为存在设备指纹降级和网络抖动的情况，默认2秒。可以根据实际情况调整
// $requestHandle->setTimeout(2);
// 填写设备指纹域名或者url入：http://127.0.0.1:9090
$responseData = $requestHandle->getDeviceInfo("https://constid.dingxiang-inc.com/udid/api/getDeviceInfo",
 Demo::appKey, Demo::appSecret, Demo::token);
$result = json_decode($responseData, true);
// 请求状态码。非 200 表示没有获取到设备明细信息
if ($result['stateCode'] == 200)
 echo "设备明细信息如下： : " . json_encode($result['data'], true);
else
 echo $result['message'];

3 NodeJS SDK接入

npm i dx-const-id-sdk --save

const SDK = require('dx-const-id-sdk')
const sdk = new SDK({
 appId: '您的appId',
 appSecret: '您的appSecret'
})
sdk.getDeviceInfo(token).then((data) => {
 console.log(data)
}).catch(err => {
 console.log('获取设备信息失败')
})

HTTP接口接入方法

1 请求参数

2 成功响应

{
 "stateCode": 200,
 "message": "请求响应成功",
 "data": {
 "hardId": "22e38229a7eda501c58bf3ddee1a340a",
 ......
 }
}

3 错误响应

{
 "stateCode": -10002,
 "message": "签名为空或验证失败",
 "data": null
}

HTTP接口返回参数明细说明

1 免费用户

1.1 web端返回结果

2 收费用户

2.1 移动端返回结果（部分示例，更多返回字段请联系售后支持获取）

2.2 web端返回结果（部分示例，更多返回字段请联系售后支持获取）

四、 附：隐私政策示例

建议在集成了SDK的app中增加《隐私政策声明》，来规避风险。并在客户同意隐私政策后，进行sdk的调用，示例如下：

隐私政策（拟，可根据实际情况进行修改）

根据《工业和信息化部 337号令》的规定，重点对以下四个方面开展规范整治工作。

（一）违规收集用户个人信息方面
（二）违规使用用户个人信息方面
（三）不合理索取用户权限方面
（四）为用户账号注销设置障碍方面

其中SDK涉及到第一条：收集个人信息（包括唯一设备识别码、网络设备硬件地址等信息）。

法规规定，所采集的数据项目需在隐私政策中明确声明，在客户不同意隐私政策的情况下，不允许进行采集。且申请授权需与场景相关，请根据实际情况做出合理调整。

顶象隐私服务条款

https://www.dingxiang-inc.com/about/privacy

解决方式

需要客户在集成了SDK的app中增加《隐私政策声明》，来规避风险。并在客户同意隐私政策后，进行sdk的调用。

隐私政策（拟，可根据实际情况进行修改）

一、我们如何收集和使用个人信息 为了识别设备/账号异常状态，我们将会接受并记录您所使用的设备相关信息（包括设备型号、操作系统、设备设置、唯一设备标识符（IMEI码）、网络设备硬件地址（MAC）、设备环境等软硬件特征信息，设备所在位置相关信息（包括您授权的GPS位置以及WLAN接入点、蓝牙和基站等信息）。 其中IP地址、设备版本、系统版本、生成ID、手机样式、手机名、APP应用包名、APP应用名、APP应用版本为必要信息，其他为可选信息。

二、我们如何保护您的个人信息
（一）我们已使用符合业界标准的安全防护措施保护您提供的个人信息，防止数据遭到未经授权访问、公开披露、使用、修改、损坏或丢失。我们会采取一切合理可行的措施，保护您的个人信息。例如，在您的浏览器与“服务”之间交换数据时受 SSL 加密保护；我们同时对我们网站提供 https 安全浏览方式；我们会使用加密技术确保数据的保密性；我们会使用受信赖的保护机制防止数据遭到恶意攻击；我们会部署访问控制机制，确保只有授权人员才可访问个人信息；以及我们会举办安全和隐私保护培训课程，加强员工对于保护个人信息重要性的认识。
（二）我们会采取一切合理可行的措施，确保未收集无关的个人信息。我们只会在达成本政策所述目的所需的期限内保留您的个人信息，除非需要延长保留期或受到法律的允许。
（三）互联网并非绝对安全的环境，而且电子邮件、即时通讯、及与其他我们用户的交流方式并未加密，我们强烈建议您不要通过此类方式发送个人信息。请使用复杂密码，协助我们保证您的账号安全。
（四）互联网环境并非百分之百安全，我们将尽力确保或担保您发送给我们的任何信息的安全性。如果我们的物理、技术、或管理防护设施遭到破坏，导致信息被非授权访问、公开披露、篡改、或毁坏，导致您的合法权益受损，我们将承担相应的法律责任。
（五）在不幸发生个人信息安全事件后，我们将按照法律法规的要求，及时向您告知：安全事件的基本情况和可能的影响、我们已采取或将要采取的处置措施、您可自主防范和降低风险的建议、对您的补救措施等。我们将及时将事件相关情况以邮件、信函、电话、推送通知等方式告知您，难以逐一告知个人信息主体时，我们会采取合理、有效的方式发布公告。 同时，我们还将按照监管部门要求，主动上报个人信息安全事件的处置情况。

marketing@dingxiang-inc.com

• 微信公众号

• 微信视频号

Copyright © 2026 北京顶象技术有限公司 版权所有 京ICP备17034357号-1

加入社群