集成要求
合规说明
请注意,在贵司的 App 中集成小盾提供的 SDK 产品时:
-
根据《网络安全法》《电信条例》《电信和互联网用户个人信息保护规定》等相关法律法规要求及监管实践中的标准,在贵司的最终用户首次启动 App,并在贵司开始采集信息之前,贵司应通过交互界面或设计(例如隐私政策弹窗)向最终用户完整告知收集、使用以及与第三方共享最终用户个人信息的目的、方式和范围,并征得最终用户的明示同意。
-
为向贵司提供业务安全和风控服务,小盾 SDK 将采集、处理、使用用户的手机终端唯一标志信息 IDFA、Android ID、OAID(包含 VAID、AAID)、MAC 地址、WIFI 列表、无线路由器标识(BSSID、SSID)、设备类型、设备型号、系统类型、粗略位置信息、精准位置信息、应用程序列表、运行中进程信息、网络制式、设备软件版本号、传感器信息以及传感器列表等相关设备信息。
为确保贵司使用相关服务的合规性,贵司的隐私政策应涵盖对小盾 SDK 提供服务并采集、处理、使用相关信息的授权。以上内容供贵司参考,具体表述可由贵司根据隐私协议的整体框架和内容自行确定。
个人信息处理规则(隐私政策):https://xiaodun.com/other/privacy/id=4
合规使用指导:小盾设备指纹 SDK 合规使用指导
行为采集合规说明
如果集成行为采集模块,贵司还应在 App 隐私政策中明确说明:
-
功能目的:用于识别机器行为及欺诈风险。
-
采集范围:触摸、点击、滚动、滑动、屏幕边缘滑动、缩放、文字输入行为、页面浏览及停留时间、应用进入前台或后台、设备方向、陀螺仪和加速度计等行为信息。
-
调用时机:必须在用户同意隐私政策后,才能初始化 SDK 并启动行为采集。
行为采集模块不得在用户同意隐私政策之前调用。
环境要求
| 平台 | 兼容版本 | 支持架构 |
|---|---|---|
| Android | Android 5.0 及以上 | armeabi-v7a、arm64-v8a、x86 |
| iOS | iOS 9.0 及以上 | armv7、arm64、x86_64 |
集成步骤
安装 React Native 插件
在 React Native 项目根目录执行:
npm install --save [email protected]
React Native 0.60 及以上版本支持自动链接,无须手动注册原生模块。
安装完成后,iOS 项目需要执行:
cd ios
pod install
cd ..
请使用 Xcode 打开:
ios/<YourApp>.xcworkspace
不要直接打开 .xcodeproj。
行为采集 SDK 集成
React Native 插件提供 start、collect 和 stop 桥接方法,但 Android 和 iOS 的行为采集原生 SDK 需要由宿主 App 单独集成。
这样可以避免只使用设备指纹功能时被强制引入行为采集 SDK。
Android 行为采集依赖
在宿主 App 的 android/app/build.gradle 中添加:
dependencies {
implementation 'com.trustdecision.android:behavior:1.5.1'
}
修改原生依赖后,需要重新编译并安装 App。
例如:
npm run android
或者:
cd android
./gradlew installDebug
iOS 行为采集依赖
iOS 行为采集 SDK 使用 Swift Package Manager 集成,不再通过 React Native 插件的 Podspec 自动引入。
Swift Package Manager 集成步骤
-
使用 Xcode 打开宿主工程的:
ios/<YourApp>.xcworkspace -
选择:
File > Add Package Dependencies... -
输入仓库地址:
https://github.com/trustdecision/TDBehavior_spm -
Dependency Rule选择:Exact Version -
Version 填写:
1.5.2 -
Add to Target选择宿主 App Target。 -
点击
Add Package。
请将 TDBehavior 添加到宿主 App Target,不要添加到 Pods Project 或某个 Pod Target。
React Native 插件本身仍然通过 CocoaPods 自动链接;
Android 权限申请
在应用 Module 的 AndroidManifest.xml 文件中声明以下权限:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">
<!-- 必选权限 -->
<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"/>
<!-- 如果应用面向海外市场并在 Google Play 发布,请添加此权限 -->
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
<!--
以下权限为可选权限。
不声明将放弃部分设备信息采集,可能影响设备指纹精准度。
-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<!--
Android 11 及以上获取应用列表需要该权限。
应用列表采集涉及合规要求,请由业务方根据实际情况决定是否申请。
-->
<uses-permission
android:name="android.permission.QUERY_ALL_PACKAGES"
tools:ignore="QueryAllPackagesPermission"/>
</manifest>
权限说明
| 权限 | 是否必选 | 说明 |
|---|---|---|
INTERNET | 必选 | 允许程序访问网络并与服务器通信 |
ACCESS_NETWORK_STATE | 必选 | 获取网络连接状态 |
ACCESS_WIFI_STATE | 必选 | 获取当前 WIFI 接入状态及 WLAN 热点信息 |
AD_ID | 海外应用必选 | 获取 Google 广告 ID |
ACCESS_COARSE_LOCATION | 可选 | 获取粗略位置信息 |
ACCESS_FINE_LOCATION | 可选 | 获取精确位置信息 |
READ_PHONE_STATE | 可选 | 获取 SIM 卡相关信息 |
QUERY_ALL_PACKAGES | 可选 | 获取已安装应用列表 |
获取 TrustDevice 模块
推荐直接从 NativeModules 获取模块:
import {NativeModules} from 'react-native';
const TrustDevice = NativeModules.TrustDevice;
也可以使用插件默认导出:
import TrustDevice from 'react-native-trustdevice';
初始化 SDK
注意事项
-
必须在用户同意隐私协议后初始化 SDK。
-
行为采集同样必须在用户同意隐私协议后启动。
-
partner、appKey和dataCenter为必填参数。 -
Debug 环境必须将
debug设置为true。 -
Release 发布前应将
debug设置为false。
初始化示例
import {NativeModules} from 'react-native';
const TrustDevice = NativeModules.TrustDevice;
function initWithOptions() {
const options = {
partner: '请输入您的 partnerCode',
appKey: '请输入您的 appKey',
appName: '请输入您的 appName',
dataCenter: '请输入您接入的数据中心',
debug: false,
};
if (__DEV__) {
options.debug = true;
}
TrustDevice.initWithOptions(options);
}
获取 blackBox
注意事项
-
请在
initWithOptions之后调用getBlackBox或getBlackBoxAsync。 -
不要在 App 中长期缓存 blackBox。
-
需要使用 blackBox 时,应通过 SDK 方法实时获取。
-
建议首次优先使用
getBlackBoxAsync。 -
首次异步获取成功后,可以在实际业务节点调用
getBlackBox。
异步获取 blackBox
async function getBlackBoxAsync() {
try {
const blackBox = await TrustDevice.getBlackBoxAsync();
console.log('blackBox:', blackBox);
return blackBox;
} catch (error) {
console.error('getBlackBoxAsync failed:', error);
throw error;
}
}
获取 blackBox
async function getBlackBox() {
try {
const blackBox = await TrustDevice.getBlackBox();
console.log('blackBox:', blackBox);
return blackBox;
} catch (error) {
console.error('getBlackBox failed:', error);
throw error;
}
}
业务调用示例
async function register() {
const blackBox = await TrustDevice.getBlackBox();
const requestBody = {
username: 'example',
blackBox,
};
// 调用注册接口
// await requestRegister(requestBody);
}
行为采集
行为采集方法
React Native 插件提供以下方法:
async function start(): Promise<void>;
async function collect(): Promise<{
code: number;
payload: string;
msg: string;
}>;
async function stop(): Promise<void>;
方法说明
start
开始行为采集,并将采集到的数据写入 SDK 内部容器。
建议在进入需要识别用户行为的业务页面时调用,例如:
-
登录页面
-
注册页面
-
找回密码页面
-
支付确认页面
-
重要信息修改页面
await TrustDevice.start();
collect
获取当前已采集的行为数据。
const result = await TrustDevice.collect();
返回结构:
{
code: 0,
payload: '行为采集数据',
msg: ''
}
字段说明:
| 字段 | 类型 | 说明 |
|---|---|---|
code | number | 返回码,0 表示成功 |
payload | string | 行为采集结果,成功时提交给业务服务端 |
msg | string | 失败时的错误信息 |
stop
停止行为采集,并清空尚未通过 collect 获取的数据。
await TrustDevice.stop();
建议在离开业务页面或不再需要行为采集时调用。
完整调用流程
行为采集的标准调用顺序是:
用户同意隐私政策
↓
initWithOptions
↓
进入业务页面
↓
start
↓
用户进行输入、点击或滑动等真实操作
↓
collect
↓
将 payload 随业务请求提交
↓
离开业务页面
↓
stop
React Native 完整示例
import React, {useEffect, useRef, useState} from 'react';
import {
Button,
NativeModules,
Text,
TextInput,
View,
} from 'react-native';
const TrustDevice = NativeModules.TrustDevice;
const SDK_OPTIONS = {
partner: '请输入您的 partnerCode',
appKey: '请输入您的 appKey',
appName: '请输入您的 appName',
dataCenter: 'cn',
debug: __DEV__,
};
export default function LoginPage() {
const [username, setUsername] = useState('');
const [resultText, setResultText] = useState('');
const collectingRef = useRef(false);
useEffect(() => {
TrustDevice.initWithOptions(SDK_OPTIONS);
return () => {
if (collectingRef.current) {
TrustDevice.stop().catch(error => {
console.error('stop behavior failed:', error);
});
}
};
}, []);
const startBehavior = async () => {
try {
await TrustDevice.start();
collectingRef.current = true;
setResultText('行为采集已开始');
} catch (error) {
console.error('start failed:', error);
setResultText(`行为采集启动失败:${String(error)}`);
}
};
const submitLogin = async () => {
try {
const blackBox = await TrustDevice.getBlackBoxAsync();
const behaviorResult = await TrustDevice.collect();
if (behaviorResult.code !== 0) {
console.error(
'collect failed:',
behaviorResult.code,
behaviorResult.msg,
);
setResultText(
`行为采集失败:${behaviorResult.code} ${behaviorResult.msg}`,
);
return;
}
const requestBody = {
username,
blackBox,
behaviorPayload: behaviorResult.payload,
};
console.log('login request:', requestBody);
// 将 blackBox 和 behaviorPayload 随业务请求提交到服务端
// await requestLogin(requestBody);
setResultText('行为数据获取成功');
} catch (error) {
console.error('submit login failed:', error);
setResultText(`登录处理失败:${String(error)}`);
}
};
const stopBehavior = async () => {
try {
await TrustDevice.stop();
collectingRef.current = false;
setResultText('行为采集已停止');
} catch (error) {
console.error('stop failed:', error);
setResultText(`停止行为采集失败:${String(error)}`);
}
};
return (
<View>
<Button
title="进入登录流程并开始采集"
onPress={startBehavior}
/>
<TextInput
value=USERNAME
onChangeText={setUsername}
placeholder="请输入用户名"
/>
<Button
title="登录"
onPress={submitLogin}
/>
<Button
title="停止采集"
onPress={stopBehavior}
/>
<Text>{resultText}</Text>
</View>
);
}
行为采集返回码
| 返回码 | 描述 | 处理建议 |
|---|---|---|
0 | 成功 | 使用返回的 payload |
100 | 没有调用 initWithOptions | 先初始化 SDK,再调用行为采集方法 |
101 | 网络鉴权结果尚未返回 | 检查网络并稍后重新调用 collect |
102 | 鉴权请求发生网络错误 | 检查网络连接并重试 |
103 | 鉴权接口返回非 200 状态码 | 检查 partner 等参数;仍失败时将 msg 提供给运营人员 |
104 | SDK 内部没有采集到行为数据 | 确保已经调用 start,并在调用 collect 前产生输入、点击或滑动等行为 |
109 | 采集开关全部关闭 | 将返回的 msg 提供给运营人员排查 |
110 | 调用 collect 前没有调用 start | 按照 start → 用户操作 → collect 的顺序调用 |
获取 SDK 版本号
async function getSDKVersion() {
const version = await TrustDevice.getSDKVersion();
console.log('SDK version:', version);
}
Android 混淆配置
如果 Android 项目使用 ProGuard 或 R8,请添加:
-keep class com.trustdecision.** { *; }
全部初始化配置
| 配置 Key | 说明 | 平台 | 示例 |
|---|---|---|---|
partner | 合作方编码,请联系运营人员获取 | 全平台 | options["partner"] = "合作方编码" |
appKey | 应用标识 | 全平台 | options["appKey"] = "appKey" |
dataCenter | 数据中心:cn 中国、sg 新加坡、us 北美、fra 欧洲、idna 印尼 | 全平台 | options["dataCenter"] = "cn" |
appName | 应用名称,请联系运营人员获取 | 全平台 | options["appName"] = "App" |
debug | 反调试配置;开发阶段开启,正式发布时关闭 | 全平台 | options["debug"] = true |
timeLimit | 网络请求超时时间,单位为秒,默认 15 秒 | 全平台 | options["timeLimit"] = 5 |
location | 是否采集地理位置信息,默认开启 | 全平台 | options["location"] = true |
IDFA | 是否采集广告标识符,默认开启 | iOS | options["IDFA"] = true |
deviceName | 是否采集设备名称,默认开启 | iOS | options["deviceName"] = true |
runningTasks | 是否获取正在运行的任务,默认开启 | Android | options["runningTasks"] = true |
sensor | 是否采集传感器信息,默认开启 | Android | options["sensor"] = true |
readPhone | 是否采集 READ_PHONE_STATE 权限相关信息,默认开启 | Android | options["readPhone"] = true |
installPackageList | 是否采集安装包列表,默认开启 | Android | options["installPackageList"] = true |
常见问题
Android 提示 Behavior 类不存在
确认依赖添加在宿主 App Module:
dependencies {
implementation 'com.trustdecision.android:behavior:1.5.1'
}
添加依赖后执行一次 Clean 和重新构建:
cd android
./gradlew clean
cd ..
npm run android
iOS 提示 TDBehavior 不可用
确认:
-
已通过 Swift Package Manager 添加:
https://github.com/trustdecision/TDBehavior_spm -
使用的是 Exact Version
1.5.2。 -
TDBehavior产品添加到了宿主 App Target。 -
使用
.xcworkspace打开项目。 -
修改依赖后已经重新编译并安装 App。
