com.trustdecision.cordova

v0.2.3

Published

17 days ago

Cordova 设备指纹插件，集成 Android/iOS 原生 SDK

0High
0Medium
0Low

trustdevice-trustdecision

ecosystem:cordova cordova-android cordova-ios trustdecision trustdevice

Trustdevice Cordova Plugin

用于 Cordova 场景的设备指纹插件，对外提供统一的 JS 调用入口，并桥接到 Android / iOS 原生 SDK。

支持平台：

Android 原生 SDK com.trustdecision.android:mobrisk:+
iOS 原生 SDK TrustDecisionPro（安装时解析最新可用版本）

集成要求

合规说明

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

根据《网络安全法》《电信条例》《电信和互联网用户个人信息保护规定》等相关法律法规要求及监管实践中的标准，在最终用户首次启动 App 并在开始采集信息之前，贵司应以交互界面或设计向最终用户完整告知收集、使用、与第三方共享个人信息的目的、方式和范围，并征得最终用户的明示同意。
为提供业务安全和风控服务，小盾 SDK 可能采集并处理设备标识、网络环境、位置信息、应用列表、运行任务、传感器等相关信息。前述内容应由宿主 App 在隐私政策中完成披露并取得授权。

个人信息类处理规则（隐私政策）：https://xiaodun.com/other/privacy/id=4

合规使用指导：https://cn-doc.trustdecision.com/reference/小盾设备指纹sdk合规使用指导仅适应于中国大陆

SDK 信息

| 项目 | 说明 | | --- | --- | | 插件名称 | TrustdeviceCordova | | 插件 ID | com.trustdecision.cordova | | 插件版本 | 0.2.3 | | Android SDK | com.trustdecision.android:mobrisk:+ | | iOS SDK | TrustDecisionPro（安装时解析最新可用版本） |

环境要求

| 项目 | Android | iOS | | --- | --- | --- | | Cordova 引擎 | cordova >= 12.0.0、cordova-android >= 13.0.0 | cordova >= 12.0.0、cordova-ios >= 7.1.1 | | 系统版本 | Android 5.0 及以上 | iOS 9.0 及以上 | | 开发环境 | Java 17+、Android Studio 或本地 Android SDK / Gradle | 完整 Xcode、CocoaPods | | 支持架构 | armeabi-v7a、arm64-v8a、x86、x86_64 | armv7、arm64、x86_64 |

集成步骤

安装配置

插件安装

在 Cordova 工程目录执行插件安装命令前，请先确认 Android 集成策略。插件支持以下 Android 权限注入与依赖裁剪开关：

| 项目 | 类型 | 默认值 | 安装变量 | 说明 | | --- | --- | --- | --- | --- | | INTERNET | 基础权限 | 自动注入 | - | 允许程序访问网络连接，发送请求与服务器进行通信 | | ACCESS_NETWORK_STATE | 基础权限 | 自动注入 | - | 获取网络连接状态信息 | | ACCESS_WIFI_STATE | 基础权限 | 自动注入 | - | 获取当前 WiFi 接入状态以及 WLAN 热点信息 | | com.google.android.gms.permission.AD_ID | 可选权限 | false | TD_ANDROID_ENABLE_AD_ID | 海外场景获取 Google 广告 ID | | ACCESS_COARSE_LOCATION | 可选权限 | false | TD_ANDROID_ENABLE_LOCATION_PERMISSION | 获取粗略位置信息 | | ACCESS_FINE_LOCATION | 可选权限 | false | TD_ANDROID_ENABLE_LOCATION_PERMISSION | 获取精确位置信息 | | READ_PHONE_STATE | 可选权限 | false | TD_ANDROID_ENABLE_READ_PHONE_STATE_PERMISSION | 读取 SIM 卡相关信息 | | QUERY_ALL_PACKAGES | 可选权限 | false | TD_ANDROID_ENABLE_QUERY_ALL_PACKAGES_PERMISSION | 获取应用程序列表，涉及较强合规约束 | | packagelist/readphone/location/sensor/wifiinfo | 依赖裁剪 | none | TD_ANDROID_EXCLUDE_MODULES | 在 Android 依赖阶段裁剪指定采集模块，不负责权限声明 |

说明：

基础权限会随插件安装自动注入宿主 AndroidManifest.xml。
可选权限默认不会自动注入；如业务确认需要，请在首次安装插件时通过安装变量显式开启。
TD_ANDROID_EXCLUDE_MODULES 用于 Android 依赖裁剪，不负责权限声明。
ACCESS_COARSE_LOCATION、ACCESS_FINE_LOCATION、READ_PHONE_STATE 仍需宿主 App 自行申请运行时权限；插件不负责 requestPermissions 等运行时权限桥接。
QUERY_ALL_PACKAGES 不属于运行时权限，但属于高敏感清单声明项，应由宿主结合实际业务场景与商店政策按需开启。

安装方式如下：

通过 npm registry 安装：

cordova plugin add com.trustdecision.cordova \
  --variable TD_ANDROID_ENABLE_AD_ID=true \
  --variable TD_ANDROID_ENABLE_LOCATION_PERMISSION=true \
  --variable TD_ANDROID_ENABLE_READ_PHONE_STATE_PERMISSION=true \
  --variable TD_ANDROID_ENABLE_QUERY_ALL_PACKAGES_PERMISSION=true

如需在安装时同时裁剪 Android 采集模块，可继续附加 TD_ANDROID_EXCLUDE_MODULES，例如：

cordova plugin add com.trustdecision.cordova \
  --variable TD_ANDROID_ENABLE_QUERY_ALL_PACKAGES_PERMISSION=true \
  --variable TD_ANDROID_EXCLUDE_MODULES=readphone,sensor

如果插件已经安装，而后续又需要调整 Android 可选权限或依赖裁剪变量，建议移除后重新安装：

cordova plugin rm com.trustdecision.cordova
cordova plugin add com.trustdecision.cordova \
  --variable TD_ANDROID_ENABLE_AD_ID=true \
  --variable TD_ANDROID_ENABLE_LOCATION_PERMISSION=true \
  --variable TD_ANDROID_ENABLE_READ_PHONE_STATE_PERMISSION=true \
  --variable TD_ANDROID_ENABLE_QUERY_ALL_PACKAGES_PERMISSION=true

初始化

注意事项

请确保在用户同意隐私协议后再进行 SDK 初始化。
推荐先调用 setOnErrorCodeListener(listener)，再调用 initWithOptions(options)。
推荐在应用启动阶段先调用一次 getBlackBoxAsync() 预热，在注册、登录、支付等真实业务节点调用 getBlackBox()。
多次注册错误码监听时，插件会释放上一次监听，仅保留最后一次注册结果。

方法定义

插件对外暴露以下 JS 方法：

window.TrustdeviceCordova.setOnErrorCodeListener(listener)
window.TrustdeviceCordova.initWithOptions(options)
window.TrustdeviceCordova.getBlackBoxAsync()
window.TrustdeviceCordova.getBlackBox()
window.TrustdeviceCordova.getSDKVersion()

方法说明：

| 方法 | 说明 | 返回值 | | --- | --- | --- | | setOnErrorCodeListener(listener) | 注册原生错误码监听器 | Promise<void> | | initWithOptions(options) | 初始化 SDK | Promise<void> | | getBlackBoxAsync() | 异步获取 blackBox | Promise<string> | | getBlackBox() | 同步语义获取 blackBox，内部仍在原生线程执行 | Promise<string> | | getSDKVersion() | 获取当前平台 SDK 版本号 | Promise<string> |

调用示例

document.addEventListener('deviceready', async () => {
  await window.TrustdeviceCordova.setOnErrorCodeListener(function (errorCode, errorMsg, payload) {
    console.log('trustdecision error', errorCode, errorMsg, payload);
  });

  await window.TrustdeviceCordova.initWithOptions({
    partner: 'your-partner',
    appKey: 'your-app-key',
    country: 'cn',
    appName: 'CordovaSmoke',
    channel: 'your-channel',
    debug: true,
    timeLimit: 15,
    customMessage: 'your-custom-message',
    location: true,
    IDFA: true,
    deviceName: true,
    runningTasks: true,
    sensor: true,
    readPhone: true,
    installPackageList: true
  });

  const sdkVersion = await window.TrustdeviceCordova.getSDKVersion();
  const preload = await window.TrustdeviceCordova.getBlackBoxAsync();
  const result = await window.TrustdeviceCordova.getBlackBox();

  console.log(sdkVersion, preload, result);
});

全部配置

initWithOptions(options) 的配置说明如下：Android 侧按白名单映射到 TDRisk.Builder，iOS 侧在少量兼容转换后会将整个 options 字典继续传给 SDK。

| 配置 key | 说明 | 平台 | 示例代码 | 影响的sdk字段 | | --- | --- | --- | --- | --- | | partner(必须) | 合作方编码，请联系运营获取 | All | options.partner = 'your-partner' | - | | appKey(必须) | 应用标识 | All | options.appKey = 'your-app-key' | - | | country(必须) | cn/sg/us/fra/idna 等国家地区标识。iOS 按原样透传，Android 显式映射到 TDRisk.COUNTRY_* 常量 | All | options.country = 'cn' | - | | appName | 应用名称，请联系运营获取 | All | options.appName = 'CordovaSmoke' | - | | channel | 渠道标识，请联系运营获取 | All | options.channel = 'your-channel' | - | | debug | 反调试功能。Android 侧传 false 时禁用调试，iOS 侧传 true 时透传 allowed | All | options.debug = true | - | | timeLimit | 网络请求回调超时时间，单位秒，默认为 15s | All | options.timeLimit = 5 | - | | customMessage | 自定义消息，SDK 支持透传和存储 | All | options.customMessage = 'your-custom-message' | - | | location | 是否采集地理位置信息，默认开启 | All | options.location = true | - | | IDFA | 是否采集广告标识符，默认开启 | iOS | options.IDFA = true | idfa | | IDFV | 是否采集应用开发厂商标识符，默认开启 | iOS | options.IDFV = false | idfv | | wifiIp | 是否采集 wifiIp，默认开启 | iOS | options.wifiIp = false | wifiIp | | cellIp | 是否采集 cellIp，默认开启 | iOS | options.cellIp = false | cellIp | | vpnIp | 是否采集 vpnIp，默认开启 | iOS | options.vpnIp = false | vpnIp | | wifiIpv6 | 是否采集 wifiIpv6，默认开启 | iOS | options.wifiIpv6 = false | wifiIpv6 | | deviceName | 是否采集设备名称，默认开启 | iOS | options.deviceName = true | device_name | | ssid | 是否采集 ssid 信息，默认开启 | iOS | options.ssid = false | ssid | | collectLevel | 配置 blackBox 裁剪长度，可传 M | iOS | options.collectLevel = 'M' | - | | runningTasks | 是否获取正在运行的任务，默认开启 | Android | options.runningTasks = true | running_packages | | sensor | 是否采集传感器信息，默认采集 | Android | options.sensor = true | mangetic_field_sensor、gyroscope_sensor、light_sensor、accelerator_data、gravity_data | | readPhone | 是否采集 READ_PHONE_STATE 权限相关信息，默认采集 | Android | options.readPhone = true | country_iso、carrier、network_operator、sim_operator、phone_type、radio_type、device_svn | | installPackageList | 是否采集安装包列表，默认采集 | Android | options.installPackageList = true | installed_packages |

隐私文件配置

根据苹果公司公布的最新 App Store 隐私政策，自 2024 年春季开始，上架 App Store 的应用需要携带一份 App 的隐私清单文件。从 2024 年 5 月 1 日开始，App Store Connect 不接受未在隐私清单文件中描述其使用所需原因 API 的应用程序。

适配措施

请根据实际情况选择对应方案：

工程目录中不存在 PrivacyInfo.xcprivacy 文件

在工程目录下通过 Xcode 新建 App Privacy 类型文件，命名为 PrivacyInfo，并勾选需要的 Targets。
在工程目录中选中 PrivacyInfo.xcprivacy 文件，通过 Open As -> Source Code 的方式打开文件。
将下方 SDK 的 PrivacyInfo.xcprivacy 内容粘贴到宿主工程文件中。

工程目录中已存在 PrivacyInfo.xcprivacy 文件

在工程目录中选中 PrivacyInfo.xcprivacy 文件，通过 Open As -> Source Code 的方式打开文件。
将下方 SDK 的 PrivacyInfo.xcprivacy 中缺失但宿主工程尚未声明的内容补齐。

SDK 的 PrivacyInfo.xcprivacy

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>NSPrivacyCollectedDataTypes</key>
	<array>
		<dict>
			<key>NSPrivacyCollectedDataType</key>
			<string>NSPrivacyCollectedDataTypeDeviceID</string>
			<key>NSPrivacyCollectedDataTypeLinked</key>
			<true/>
			<key>NSPrivacyCollectedDataTypeTracking</key>
			<false/>
			<key>NSPrivacyCollectedDataTypePurposes</key>
			<array>
				<string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
				<string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
			</array>
		</dict>
	</array>
	<key>NSPrivacyAccessedAPITypes</key>
	<array>
		<dict>
			<key>NSPrivacyAccessedAPIType</key>
			<string>NSPrivacyAccessedAPICategoryDiskSpace</string>
			<key>NSPrivacyAccessedAPITypeReasons</key>
			<array>
				<string>E174.1</string>
			</array>
		</dict>
		<dict>
			<key>NSPrivacyAccessedAPIType</key>
			<string>NSPrivacyAccessedAPICategoryUserDefaults</string>
			<key>NSPrivacyAccessedAPITypeReasons</key>
			<array>
				<string>CA92.1</string>
			</array>
		</dict>
		<dict>
			<key>NSPrivacyAccessedAPIType</key>
			<string>NSPrivacyAccessedAPICategorySystemBootTime</string>
			<key>NSPrivacyAccessedAPITypeReasons</key>
			<array>
				<string>35F9.1</string>
			</array>
		</dict>
	</array>
</dict>
</plist>

已知限制

iOS 构建依赖完整 Xcode 与 CocoaPods。
Android 构建依赖本地 Android SDK / Gradle 环境。
iOS 当前仍保留“整体透传 options”行为，Android 当前仍为白名单桥接，两端参数生效范围并不完全一致。

目录结构

Cordova/
├── plugin.xml
├── package.json
├── README.md
├── example/
│   ├── config.xml
│   ├── package.json
│   ├── scripts/
│   └── www/
├── scripts/
│   └── android-compliance-config.js
├── www/
│   └── trustdevice-cordova.js
└── src/
    ├── android/
    │   ├── TrustdeviceCordova.java
    │   ├── TrustdecisionRiskUtils.java
    │   └── trustdevice-cordova.gradle
    └── ios/
        └── TrustdeviceCordova.m

错误码说明

Cordova 插件存在两类“错误码/错误信息”来源，接入时建议区分处理：

Promise reject：表示 Cordova 桥接层或插件调用失败，返回值为 { code, message, details? }。
setOnErrorCodeListener(listener)：表示原生 SDK 运行时上报的业务错误码，回调参数为 (errorCode, errorMsg, payload)。

Cordova 插件异常码

以下异常码来自插件 JS / 桥接层，通常通过 initWithOptions()、getBlackBox()、getBlackBoxAsync() 等方法的 Promise reject 返回：

| 异常码 | 说明 | 处理建议 | | --- | --- | --- | | NOT_INITIALIZED | 在 SDK 初始化前调用了 getBlackBox() 或 getBlackBoxAsync() | 先执行 initWithOptions(options)，再获取 blackBox | | INVALID_ARGUMENT | 传入参数不合法，例如缺少 partner、appKey、country 等必填项 | 按错误信息补齐或修正初始化参数 | | SDK_INIT_FAILED | 原生 SDK 初始化失败 | 优先检查初始化参数、原生依赖集成、平台环境是否完整 | | SDK_CALL_FAILED | 调用原生 SDK 方法失败，例如注册错误码监听或获取 blackBox 失败 | 结合 message / details 排查具体调用环节 | | INTERNAL_ERROR | 插件内部错误，或当前 Cordova 插件环境不可用 | 检查是否已进入 deviceready、插件是否正确安装、当前运行环境是否支持 Cordova |

原生 SDK 错误码

以下错误码通过 setOnErrorCodeListener(listener) 回调返回。 | 错误码 | 说明 | 处理建议 | | --- | --- | --- | | 100 | App 启动后未按顺序调用初始化和取值接口 | 先调用 initWithOptions()，再调用 getBlackBoxAsync() / getBlackBox() | | 101 | 不影响使用，但当前 blackBox 可能不是最优长度 | 如希望获取更短的 blackBox，按上文最佳实践先预热再在业务节点取值 | | 102 | 不影响使用，但同步取值时机不理想 | 尽量在 getBlackBoxAsync() 成功后，再调用 getBlackBox() | | 200 | 必传参数异常 | 根据错误信息检查并调整 partner、appKey、country 等参数 | | 201 | appKey 有效期异常 | 联系运营人员更新 appKey | | 301 | 平台差异码：iOS 表示网络异常；Android 表示接口超时 | iOS 先检查设备和 App 网络状态；Android 额外检查 appKey、partnerCode、包名/签名是否匹配，以及 timeLimit 是否设置过短 | | 302 | 平台差异码：iOS 表示初始化参数或包名/签名校验异常；Android 表示网络异常 | iOS 检查 appKey、partnerCode、包名、签名信息；Android 检查当前网络是否可用 | | 400 | 仅 Android：ABI 架构或 so 文件异常 | 重点检查宿主 App 的 ABI 配置是否在 SDK 支持范围内，以及 so 文件是否缺失 | | -1 | 未分类异常 | 请提供本次 blackBox、errorCode、errorMsg 给技术人员协助排查 |