ReactNative

集成要求

合规说明

请注意,在贵司的 App 中集成小盾提供的 SDK 产品时:

  1. 根据《网络安全法》《电信条例》《电信和互联网用户个人信息保护规定》等相关法律法规要求及监管实践中的标准,在贵司的最终用户首次启动 App,并在贵司开始采集信息之前,贵司应通过交互界面或设计(例如隐私政策弹窗)向最终用户完整告知收集、使用以及与第三方共享最终用户个人信息的目的、方式和范围,并征得最终用户的明示同意。

  2. 为向贵司提供业务安全和风控服务,小盾 SDK 将采集、处理、使用用户的手机终端唯一标志信息 IDFA、Android ID、OAID(包含 VAID、AAID)、MAC 地址、WIFI 列表、无线路由器标识(BSSID、SSID)、设备类型、设备型号、系统类型、粗略位置信息、精准位置信息、应用程序列表、运行中进程信息、网络制式、设备软件版本号、传感器信息以及传感器列表等相关设备信息。

为确保贵司使用相关服务的合规性,贵司的隐私政策应涵盖对小盾 SDK 提供服务并采集、处理、使用相关信息的授权。以上内容供贵司参考,具体表述可由贵司根据隐私协议的整体框架和内容自行确定。

个人信息处理规则(隐私政策):https://xiaodun.com/other/privacy/id=4

合规使用指导:小盾设备指纹 SDK 合规使用指导

行为采集合规说明

如果集成行为采集模块,贵司还应在 App 隐私政策中明确说明:

  1. 功能目的:用于识别机器行为及欺诈风险。

  2. 采集范围:触摸、点击、滚动、滑动、屏幕边缘滑动、缩放、文字输入行为、页面浏览及停留时间、应用进入前台或后台、设备方向、陀螺仪和加速度计等行为信息。

  3. 调用时机:必须在用户同意隐私政策后,才能初始化 SDK 并启动行为采集。

行为采集模块不得在用户同意隐私政策之前调用。

环境要求

平台兼容版本支持架构
AndroidAndroid 5.0 及以上armeabi-v7a、arm64-v8a、x86
iOSiOS 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 集成步骤

  1. 使用 Xcode 打开宿主工程的:

    ios/<YourApp>.xcworkspace
    
  2. 选择:

    File > Add Package Dependencies...
    
  3. 输入仓库地址:

    https://github.com/trustdecision/TDBehavior_spm
    
  4. Dependency Rule 选择:

    Exact Version
    
  5. Version 填写:

    1.5.2
    
  6. Add to Target 选择宿主 App Target。

  7. 点击 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: ''
}

字段说明:

字段类型说明
codenumber返回码,0 表示成功
payloadstring行为采集结果,成功时提交给业务服务端
msgstring失败时的错误信息

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 提供给运营人员
104SDK 内部没有采集到行为数据确保已经调用 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是否采集广告标识符,默认开启iOSoptions["IDFA"] = true
deviceName是否采集设备名称,默认开启iOSoptions["deviceName"] = true
runningTasks是否获取正在运行的任务,默认开启Androidoptions["runningTasks"] = true
sensor是否采集传感器信息,默认开启Androidoptions["sensor"] = true
readPhone是否采集 READ_PHONE_STATE 权限相关信息,默认开启Androidoptions["readPhone"] = true
installPackageList是否采集安装包列表,默认开启Androidoptions["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 不可用

确认:

  1. 已通过 Swift Package Manager 添加:

    https://github.com/trustdecision/TDBehavior_spm
    
  2. 使用的是 Exact Version 1.5.2。

  3. TDBehavior 产品添加到了宿主 App Target。

  4. 使用 .xcworkspace 打开项目。

  5. 修改依赖后已经重新编译并安装 App。