TrustDecision
API Reference
English

Android-通用场景

集成要求

合规说明

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

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

1.2 为向贵司提供业务安全和风控服务，同盾SDK将采集、处理、使用用户的手机终端唯一标志信息IDFA、Android ID、OAID、GAID、MAC 地址、无线IP地址、WIFI列表、无线路由器标识（BSSID、SSID）、设备类型、设备型号、系统类型、位置信息（粗略位置信息、精准位置信息）、登录 IP 地址等设备信息。为确保贵司使用相关服务的合规性，前述隐私政策应涵盖对同盾SDK提供服务并采集、处理、使用相关信息的授权，以下条款内容供贵司参考，具体表述可由贵司根据贵司隐私协议的整体框架和内容自行确定：

同盾SDK：为了业务安全和风控，我司使用了同盾 SDK，该 SDK 需要获取您的手机终端设备标识 IDFA、Android ID、OAID、GAID、MAC 地址、无线IP地址、WIFI列表、无线路由器标识（BSSID、SSID）、设备类型、设备型号、系统类型、位置信息（粗略位置信息、精准位置信息）、登录 IP 地址、应用程序列表、运行中进程信息、网络制式、设备软件版本号、传感器（光传感器、重力传感器、磁场传感器、加速度传感器、陀螺仪传感器、心率传感器）相关设备信息，用于设备欺诈风险识别。

同盾隐私协议：https://www.tongdun.cn/other/privacy/id=1

Google Play 的数据安全要求

对于上传到 Google Play 商店的每款应用，Google 都要求向所有用户公开应用的隐私和安全做法。因此，当应用（或新版本）上传到 Play 商店时，Google 要求应用开发者填写数据安全表单。有关详细信息，请参阅为 Google Play 的数据安全部分提供信息。

如果您的应用包含我们的Android SDK，那么您可以使用下表作为参考来填写数据安全表单：

Google Play 控制台数据安全表单中的问题回复
您的应用是否收集或共享任何所需的用户数据类型？是的
收集什么类型的数据？设备或其他标识符
这些数据是被收集、共享，还是两者兼而有之？收集
这些数据是暂时处理的吗？是的
为什么要收集这些用户数据？欺诈预防、安全和合规

环境要求

说明
兼容版本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.4.4'
 }

如果遇到合规性问题，可以在依赖阶段排除相关模块的采集

dependencies {
    // 设备指纹
    implementation('com.trustdecision.android:mobrisk:4.4.4'){
    		
      	// 移除后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();

最佳实践

  1. 在应用入口Application的onCreate方法中初始化
// 应用入口APPlication的onCreate
TDRisk.Builder builder = new TDRisk.Builder()
/*************************** 必传 ***************************/
.partner("demo")        // 同盾的合作⽅编码，请填写⾃身的合作⽅编码
.appKey("appKey")           // 配置AppKey，请联系同盾运营获取		 
.country(TDRisk.COUNTRY_CN); // 国家地区参数，列表可以参考下文全部配置说明
/*************************** 必传 ***************************/
if(⽤户同意隐私协议){
  TDRisk.initWithOptions(getApplicationContext(), builder);
}

  1. 在实际业务节点获取blackBox

    1. 推荐使用异步的方式获取，不影响调用线程

      public void register() {
  ...
  TDRisk.getBlackBox(new TDRiskCallback() {
  	@Override
  	public void onEvent(String blackbox) {
    	// 此处回调在新开辟的子线程
    	// ⽹络正常的情况下，会在1-2s内返回结果；⽹络异常的情况下，会在超时时间（默认最长15s）后返回
    	Log.i("TD", "init & get success");
  }
});
  ...
}

    2. 如果此前已经通过异步的方式成功获取过blackBox，则可以使用同步的方式直接获取blackBox

      public void pay() {
  ...
  // 可能耗时，谨慎在主线程调用
  String blackBox = TDRisk.getBlackBox();
  ...
}

状态检查

  1. 初始化成功会在 logcat中打印以下日志：
TD_JAVA: TD sdk load success
TD_JAVA: TD sdk init success
  1. SDK上报数据成功，getBlackBox()返回的结果长度为26位字符串。如: rGPGX1678775227I9NCwcuVJCb。
  2. 异常情况下，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(必须)应用标识，参考如何申请appKeybuilder.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")
channel渠道标识，请联系运营获取builder.channel("channel")
useDemotionData降级时，是否优先使用降级数据，默认关闭build.useDemotionData(true)
httpTimeOut网络请求回调的超时时间，单位毫秒，默认15000builder.httpTimeOut(5000)
collectLevel配置降级blackBox裁剪长度，默认L大部分为5000字符左右，配置M后大部分在2000-5000字符区间，目前仅支持这两种配置。builder.collectLevel(TDRisk.COLLECT_LEVEL_M)
disableOaid禁止采集OAID，默认允许builder.disableOaid()oaid
disableGoogleAid禁止采集GAID，默认允许builder.disableGoogleAid()aid
disableDebugger配置后，检测到调试后会终止运行，默认允许builder.disableDebugger()
disableRunningTasks禁止获取正在运行的任务，默认允许builder.disableRunningTasks()running_packages
disableGPS禁止采集GPS位置信息，默认允许builder.disableGPS()ssid、wifi_list、gps_switch、latitude、longitude、gps_location
disableSensor禁止采集传感器信息，默认允许builder.disableSensor()mangetic_field_sensor、gyroscope_sensor、light_sensor、accelerator_data、gravity_data
disableReadPhone禁止采集READ_PHONE_STATE权限相关信息，默认允许builder.disableReadPhone()country_iso、carrier、network_operator、sim_operator、phone_type、radio_type、device_svn
enableWifiMac开启采集WIFI MAC地址, 默认不采集builder.enableWifiMac()wifi_mac
disableInstallPackageList禁止采集应用列表信息，默认采集builder.disableInstallPackageList()installed_packages
customMessage自定义消息，sdk支持透传和存储builder.customMessage(customMessage)

错误码说明

错误码处理方式
100App启动后请保证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和错误信息给到技术人员协助排查