API Reference
English

Flutter

仅支持Android和iOS

集成要求

合规说明

请注意,在贵司的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

环境要求

AndroidiOS
兼容版本Android 5.0及以上系统iOS9.0及以上系统
支持架构armeabi, armeabi-v7a, arm64-v8a, x86armv7,arm64,x86_64

集成步骤

集成活体检测SDK共有3个步骤:

  1. 调用 获取License API,得到一个在时间有效期范围内的License。
  2. 安装活体检测SDK Flutter插件,获取“livenessId”。
  3. 调用 获取结果 API,传入第2步中获得的“livenessId”,在活体检测成功时获取最佳人脸自拍照,或在失败时接收详细原因。

1.获取License API

请按 https://cn-doc.trustdecision.com/reference/liveness-api#获取license-api 步骤操作

2.安装活体检测SDK Flutter插件

插件安装

将trustdevice_pro_plugin添加到Flutter应用程序中的pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  ...
  trustdevice_pro_plugin: ^1.3.1

Android权限申请

在应⽤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"/>
</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初始化

方法定义

  Future<void> initWithOptions(Map<String, dynamic> config)

获取blackBox

注意事项

  • 请在initWithOptions后调用getBlackBox/getBlackBoxAsync
  • 不要在App内对返回的blackBox进行缓存,获取blackBox请依赖getBlackBox方法
  • 尽量在首次异步获取blackBox的成功之后,再同步获取blackBox

方法定义

  // 同步获取
  Future<String> getBlackBox()
  // 异步获取  
  Future<String> getBlackBoxAsync();

最佳实践

  1. 在应用入口Application的onCreate方法中调用初始化并异步获取blackBox
import 'package:trustdevice_pro_plugin/trustdevice_pro_plugin.dart';

class _MyAppState extends State<MyApp> {
  final _trustdeviceProPlugin = TrustdeviceProPlugin();
  
  @override
  void initState() {
    super.initState();
    _initWithOptions();
  }
  
  Future<void> _initWithOptions() async {
     var options = {
      "partner": "请输入您的合作方编码",
      "appKey": "请输入您的appKey",
      "appName": "请输入您的appName",
      "country": "请输入您所在的国家地区"
    };
    //Anti debugging switch, used during development phase
 		options["debug"] = true;
    _trustdeviceProPlugin.initWithOptions(options);
    var blackBox = await _trustdeviceProPlugin.getBlackBoxAsync();
    print("_initWithOptions blackBox: ${blackBox}");
  }
  
}
  1. 在实际业务节点同步获取blackBox
// 比如注册的时候 
Future<void> _register() async {
   var blackBox = await _trustdeviceProPlugin.getBlackBox();
   // ...
}

状态检查

  1. SDK上报数据成功,getBlackBox()返回的结果长度为26位字符串。如: rGPGX1678775227I9NCwcuVJCb
  2. 异常情况下,getBlackBox()返回的结果长度可能达到5000字符,详情可查看正常blackBox和降级blackBox的差异

其他说明

获取版本号

  Future<String> getSDKVersion()

混淆打包

如果开发者需要使用 proguard 进行混淆打包,请在 proguard 配置文件添加如下代码:

-keep class cn.tongdun.**{*;}
-keep class com.trustdecision.**{*;}

全部配置

配置 key说明平台示例代码
partner(必须)合作方编码,请联系运营获取Alloptions["partner"] = "请输入您的合作方编码"
appKey(必须)应用标识,参考如何申请appKeyAlloptions["appKey"] = "请输入您的appKey"
country(必须)cn代表中国,sg代表新加坡,us代表北美,fra代表欧洲,idna代表印尼Alloptions["country"] = "请输入您所在的国家地区"
appName应用名称,请联系运营获取Alloptions["appName"] = "请输入您的appName"
debug反调试功能,默认关闭,开发阶段请打开,发布时关闭Alloptions["debug"] = true
timeLimit网络请求回调的超时时间,单位秒,默认为15sAlloptions["timeLimit"] = 5
location是否采集地理位置信息,默认开启Alloptions["location"] = true
collectLevel配置降级blackBox裁剪长度,默认5000字符,配置M后2000字符左右,目前仅支持MAlloptions["collectLevel"] = "M"
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

活体功能模块

安装活体库依赖

iOS

1.双击打开 Runner.xcworkspace 工程;

2.找到 trustdevice_pro_plugin.podspec 文件;

3.在 trustdevice_pro_plugin.podspec 文件中添加活体库依赖

  s.dependency 'TrustDecisionLiveness'

4.在 Runner.xcworkspace 所在文件夹下,执行

  pod install --repo-update 

Android

1.打开 android/build.gradle 文件

2 在 android/build.gradle 文件中添加活体库依赖

dependencies {
    implementation 'com.trustdecision.android:liveness:+'
}

initWithOptions选传参数

配置 key 定义 说明 场景 示例代码
language 语言类型
Default: en 英语 Options:
en 英语
zh-Hans 简体中文
zh-Hant 繁體中文
es 西班牙语
id 印尼语
ar 阿拉伯语
fil 菲律宾语
ko 韩语
pt 葡萄牙语
ru 俄语
th 泰语
tr 土耳其语
vi 越南语
客户根据需要设置语言类型 options["language"] = "en"
playAudio 是否播报语音 默认为 NO,不播报语音 开启后,会播报对应提示语音 options["playAudio"] = false
livenessDetectionThreshold 活体检测难易度阈值 活体检测难易度阈值,分为high、medium、low三个等级 默认为medium,中等难度 根据需要,调整为对应难度 options["livenessDetectionThreshold"] = "medium"
livenessHttpTimeOut SDK网络超时时间配置(单位:秒) 默认为15s 客户根据需要设置网络超时时间 options["livenessHttpTimeOut"] = 8
showReadyPage 启动人脸时,会弹出检测准备页面 是否显示准备页面, 默认为 YES, 即显示 关闭后,不显示准备页面,识别流程更短 options["showReadyPage"] = true
faceMissingInterval 没有检测到人脸时的超时时间 (单位:毫秒) 无人脸超时时间, 单位ms 默认为 1000ms 根据需要设置没有检测到人脸时的超时时间 options["faceMissingInterval"] = 1000
prepareStageTimeout 准备检测动作时候的起始时间 (单位:秒) 准备阶段超时时间, 单位秒 默认为 0S, 即永远不超时 根据需要设置 准备阶段超时时间 options["prepareStageTimeout"] = 0
actionStageTimeout 动作阶段中, 最长验证时间 (单位:秒) 动作阶段超时时间, 单位秒 默认为 8S 根据需要设置 动作阶段超时时间 options["actionStageTimeout"] = 8

弹出活体弹窗

示例代码

    String license = "使用您的license!!!";

    await _trustdeviceProPlugin.showLiveness(license,TDLivenessCallback(onSuccess: (String seqId,int errorCode,String errorMsg,double score,String bestImageString,String livenessId) {
          print("Liveness验证成功!seqId: $seqId,livenessId:$livenessId,bestImageString:$bestImageString");
       }, onFailed: (String seqId,int errorCode,String errorMsg,String livenessId) {
          print("Liveness验证失败!, 错误码: $errorCode 错误内容: $errorMsg");
      }));

错误码

代码提示是否计费
200success 成功(真人)
20700No face detected 没有检测到人脸
20702Person change detected 检测到换人
20703Detection timeout 检测超时
20705Screen lock or background exit during detection 检测过程中锁屏或退出后台
20710No camera permission 没有相机权限
20711User actively cancels detection on the preparation page 准备页面用户主动取消检测
20712User actively cancels detection on the detection page 检测页面用户主动取消检测
20731Face not centered 人脸未居中
20732Face not facing the screen 人脸未正对屏幕
20749Inconsistent action, tilt head down 动作不一致做出低头动作
60001Network issue, failed to retrieve session 网络问题,无法获取session
60002Network issue, failed to call anti-hack 网络问题,无法调用anti-hack
11350Internal error 内部错误

3.获取结果 API

请按 https://cn-doc.trustdecision.com/reference/liveness-api#获取结果-api 步骤操作