集成要求
合规说明
请注意,在贵司的App中集成同盾提供的SDK产品时:
1.1 根据《网络安全法》《电信条例》《电信和互联网用户个人信息保护规定》等相关法律法规要求及监管实践中的标准,在贵司的最终用户首次启动App并在贵司开始采集信息之前,贵司应以交互界面或设计(如隐私政策弹窗等)向最终用户完整告知收集、使用、与第三方共享最终用户个人信息的目的、方式和范围,并征得最终用户的明示同意。
1.2 为向贵司提供业务安全和风控服务,同盾SDK将采集、处理、使用用户的手机终端唯一标志信息(IMEI/IDFA)、Android ID、OAID、IMSI、MEID、MAC 地址、SIM 卡序列号、设备序列号、设备类型、设备型号、系统类型、地理位置、登录 IP 地址等设备信息。为确保贵司使用相关服务的合规性,前述隐私政策应涵盖对同盾SDK提供服务并采集、处理、使用相关信息的授权,以下条款内容供贵司参考,具体表述可由贵司根据贵司隐私协议的整体框架和内容自行确定:
同盾SDK:为了业务安全和风控,我司使用了同盾 SDK,该 SDK 需要获取您的手机终端唯一标志信息(IMEI/IDFA)、Android ID、OAID、IMSI、MEID、MAC 地址、SIM卡序列号、设备序列号、设备类型、设备型号、系统类型、地理位置、登录 IP 地址、应用程序列表、运行中进程信息、传感器(光传感器、重力传感器、磁场传感器、加速度传感器、陀螺仪传感器、心率传感器)相关设备信息,用于设备欺诈风险识别。 |
同盾隐私协议:https://www.tongdun.cn/other/privacy/id=1
环境要求
说明 | |
---|---|
兼容版本 | Android 5.0及以上系统 |
支持架构 | armeabi, armeabi-v7a, arm64-v8a, x86, x86_64 |
集成步骤
SDK接入示例代码(sample): https://github.com/trustdecision/mobrisk-android-sample
安装配置
如果您使用离线文件的的安装方式,请参考:离线安装SDK指导
添加仓库
在项目根目录的 build.gradle
加入maven库的配置
allprojects {
repositories {
...
mavenCentral()
}
}
如果您的 Gradle 版本是 7 或更高版本,请将下方配置添加到工程的 settings.gradle
repositories {
...
mavenCentral()
}
添加依赖
在应用主模块的 build.gradle
中,声明SDK包依赖
dependencies {
implementation 'com.trustdecision.android:mobrisk:4.3.5.1'
}
如果遇到合规性问题,可以在依赖阶段排除相关模块的采集
dependencies {
// 设备指纹
implementation('com.trustdecision.android:mobrisk:4.3.5.1'){
// 移除后sdk不获取安装包列表
exclude group: 'com.trustdecision.android', module: 'packagelist'
// 移除后sdk不会收集READ_PHONE_STATE相关信息
exclude group: 'com.trustdecision.android', module: 'readphone'
// 移除后sdk不会收集地理位置相关信息
exclude group: 'com.trustdecision.android', module: 'location'
// 移除后sdk不会收集传感器相关信息
exclude group: 'com.trustdecision.android', module: 'sensor'
// 移除后sdk不会收集wifi相关信息
exclude group: 'com.trustdecision.android', module: 'wifiinfo'
}
}
配置ABI类型
SDK目前支持 armeabi、armeabi-v7a、arm64-v8a、x86、x86_64等ABI类型,建议接入方在主模块build.gradle
文件内添加 abiFilters
配置选择所需要的架构类型,具体架构,请以您自己需要支持的架构为准!
defaultConfig {
...
ndk {
abiFilters 'armeabi-v7a', 'arm64-v8a'
}
}
配置AndroidManifest.xml
在应⽤module下的 AndroidManifest.xml ⽂件中声明以下权限
<manifest>
<!--必选权限-->
<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" />
<!-- Android11及以上获取安装包列表需要该权限,采集安装包列表涉及到⻛险合规,是否需要该权限业务⽅⾃⾏选
择 -->
<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 | 获取粗略位置信息,精度大概误差在30~1500米 |
ACCESS_FINE_LOCATION | 获取精确位置信息,定位精度达10米以内 |
READ_PHONE_STATE | 读取SIM卡相关信息 |
QUERY_ALL_PACKAGES | 获取应用程序列表 |
初始化
注意事项
- 确保在用户同意隐私协议后,再进行SDK初始化
- 保证在主进程初始化,避免初始化出现异常
方法定义
public static void initWithOptions(Context ctx, TDRisk.Builder builder)
获取blackBox
注意事项
- 请在initWithOptions后调用getBlackBox
- 不要在App内对返回的blackBox进行缓存,获取blackBox请依赖getBlackBox方法
- 尽量在首次获取blackBox的异步回调触发之后,再同步获取blackBox
方法定义
// 异步回调获取
public static String getBlackBox(TDRiskCallback callback);
// 同步获取
public static String getBlackBox();
最佳实践
- 在应用入口Application的onCreate方法中初始化
// 应用入口APPlication的onCreate
TDRisk.Builder builder = new TDRisk.Builder()
/*************************** 必传 ***************************/
.partner("demo") // 同盾的合作⽅编码,请填写⾃身的合作⽅编码
.appKey("appKey") // 配置AppKey,请联系同盾运营获取
.country(TDRisk.COUNTRY_CN); // 国家地区参数,列表可以参考下文全部配置说明
/*************************** 必传 ***************************/
if(⽤户同意隐私协议){
TDRisk.initWithOptions(getApplicationContext(), builder);
}
-
在实际业务节点获取blackBox
-
推荐使用异步的方式获取,不影响调用线程
public void register() { ... TDRisk.getBlackBox(new TDRiskCallback() { @Override public void onEvent(String blackbox) { // 此处回调在新开辟的子线程 // ⽹络正常的情况下,会在1-2s内返回结果;⽹络异常的情况下,会在超时时间(默认最长15s)后返回 Log.i("TD", "init & get success"); } }); ... }
-
如果此前已经通过异步的方式成功获取过blackBox,则可以使用同步的方式直接获取blackBox
public void pay() { ... // 可能耗时,谨慎在主线程调用 String blackBox = TDRisk.getBlackBox(); ... }
-
状态检查
- 初始化成功会在 logcat中打印以下日志:
TD_JAVA: TD sdk load success
TD_JAVA: TD sdk init success
- SDK上报数据成功,getBlackBox()返回的结果长度为26位字符串。如:
rGPGX1678775227I9NCwcuVJCb
。 - 异常情况下,getBlackBox()返回的结果长度可能达到5000字符,详情可查看正常blackBox和降级blackBox的差异
其他说明
获取版本号
TDRisk.getSDKVersion()
监听错误码
请在initWithOptions方法之前调用 setOnErrorCodeListener来监听错误信息。
TDRisk.setOnErrorCodeListener(new TDErrorCodeCallback() {
@Override
public void onResult(int errorCode, String errorMsg) {
Log.d(TAG, "errorCode:" + errorCode + "," + "errorMsg:" + errorMsg);
}
});
混淆打包
如果开发者需要使用 proguard 进行混淆打包,请在 proguard 配置文件添加如下代码:
-keep class cn.tongdun.**{*;}
全部配置
配置 key | 说明 | 示例代码 |
---|---|---|
partner(必须) | 合作方编码,请联系运营获取 | builder.partner("your partnerCode") |
appKey(必须) | 应用标识,参考如何申请appKey | builder.appKey("appKey") |
country(必须) | 数据中心地区:TDRisk.COUNTRY_US(北美) TDRisk.COUNTRY_FRA (欧洲) TDRisk.COUNTRY_SG (新加坡) TDRisk.COUNTRY_IDNA (印尼) TDRisk.COUNTRY_CN (中国) | builder.country(TDRisk.COUNTRY_CN) |
appName | 应用名称,请联系运营获取 | builder.appName("appName") |
useDemotionData | 降级时,是否优先使用缓存,默认开启 | build.useDemotionData(true) |
httpTimeOut | 网络请求回调的超时时间,单位毫秒,默认15000 | builder.httpTimeOut(5000) |
collectLevel | 配置降级blackBox裁剪长度,默认L大部分为5000字符左右,配置M后大部分在2000-5000字符区间,目前仅支持这两种配置。 | builder.collectLevel(TDRisk.COLLECT_LEVEL_M) |
disableOaid | 禁止采集OAID,默认允许 | builder.disableOaid() |
disableDebugger | 配置后,检测到调试后会终止运行,默认允许 | builder.disableDebugger() |
disableRunningTasks | 禁止获取正在运行的任务,默认允许 | builder.disableRunningTasks() |
disableGPS | 禁止采集GPS位置信息,默认允许 | builder.disableGPS() |
disableSensor | 禁止采集传感器信息,默认允许 | builder.disableSensor() |
disableReadPhone | 禁止采集READ_PHONE_STATE权限相关信息,默认允许 | builder.disableReadPhone() |
enableWifiMac | 开启采集WIFI MAC地址, 默认不采集 | builder.enableWifiMac() |
disableInstallPackageList | 禁止采集应用列表信息,默认采集 | builder.disableInstallPackageList() |
customMessage | 自定义消息,sdk支持透传和存储 | builder.customMessage(customMessage) |
错误码说明
错误码 | 处理方式 |
---|---|
100 | App启动后请保证initWithOptions在getBlackBox之前调用。 |
101 | 不影响使用,如果希望获取更短的blackBox,可按照上文最佳实践方式使用 |
102 | 不影响使用,如果希望获取更短的blackBox,尽量在getBlackBox(TDRiskCallback)成功回调后使用getBlackBox()获取 |
200 | 必传参数异常,根据错误信息调整参数 |
201 | 请联系我司运营人员更新appKey有效期 |
301 | 接口超时,请先检查初始化参数appKey、partnerCode填写是否正确;然后检查appkey和包名、签名信息是否匹配;最后检查是否通过setHttpTimeout设置了过短的超时时间。 若还是无法解决,请提供降级的blackBox、code和错误信息给到技术人员协助处理 |
302 | 网络异常,请检查手机连接的网络是否可用 |
400 | 请重点检查abi架构配置是否在SDK支持范围内;so文件是否缺失 |
-1 | 请提供本次blackbox、code和错误信息给到技术人员协助排查 |