trustdevice

# 集成要求

# 合规说明

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

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

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

同盾SDK：为了业务安全和风控，我司使用了同盾 SDK，该 SDK 需要获取您的手机终端唯一标志信息（IMEI/IDFA）、Android ID、IMSI、MEID、MAC 地址、SIM卡序列号、设备序列号、设备类型、设备型号、系统类型、地理位置、登录 IP 地址、应用程序列表、运行中进程信息、传感器（光传感器、重力传感器、磁场传感器、加速度传感器、陀螺仪传感器）相关设备信息，用于设备欺诈风险识别。

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

# 环境要求

条目 说明
兼容版本 iOS9.0+
支持架构 armv7, arm64, x86_64

# 集成步骤

# CocoaPods集成

  • 在 Podfile 文件中对应 target 中新增 pod 'TrustDecisionPro', '4.2.4.2'
  • 在 Podfile 文件中对应 target 中新增 pod 'TrustDecisionCaptcha', '2.1.8'
  • 在 Podfile 所在文件夹中执行 pod install --repo-update 命令 (M1系列mac电脑需要执行 arch -x86_64 pod install --repo-update 命令)

# SDK目录

Pods/TrustDecisionPro 文件夹下存在如下文件:

  • TDMobRisk.framework（终端SDK主文件，静态库类型）
  • TDCorePlugin.framework （终端SDK依赖核心插件，Embed动态库类型）

Pods/TrustDecisionCaptcha 文件夹下存在如下文件:

  • libTDCaptcha.a（终端SDK 验证码组件，静态库类型）
  • TDCaptchaResource.bundle （终端SDK 验证码组件需要用到的资源包)

# 引入头文件

在调用的位置引入头文件

#import <TDMobRisk/TDMobRisk.h>

# SDK初始化

注意事项

安装后首次启动时，在用户同意隐私协议后，再进行SDK初始化。

避免出现用户未同意隐私协议就进行SDK初始化采集，引发合规风险事故。

接口定义

void (*initWithOptions)(NSDictionary *options);

示例代码

- (void)initTrustDecisionSDK:(void (^)(NSString *blackbox))callback {
  TDMobRiskManager_t *riskManager = [TDMobRiskManager sharedManager];
  NSMutableDictionary *options = [NSMutableDictionary dictionary];

  /*************************** 必传 ***************************/
  // 合作方编码，如tongdun，参考下面`必传配置`
  [options setValue:@"请输入您的合作方编码" forKey:@"partner"];
  // 同盾平台注册的应用标识，参考下面`必传配置`
  [options setValue:@"请输入您的appKey" forKey:@"appKey"];
  // 同盾平台注册的应用名称，参考下面`必传配置`
  [options setValue:@"请输入您的appName" forKey:@"appName"];
  // 国家地区参数，参考下面`必传配置`
  [options setValue:@"请输入您所在的国家地区" forKey:@"country"];

  /*************************** 选传 ***************************/
#ifdef DEBUG
  // !!! DEBUG模式下若不设置此参数，app运行会闪退
  [options setValue:@"allowed" forKey:@"allowed"];
#endif
  [options setValue:^(NSString *blackbox) {
    // 此处回调在子线程
    // 网络正常的情况下，会在200-300ms内返回结果。
    // 网络异常的情况下，会在超时时间timeLimit（默认最长15s）后返回。
    // 请在下方添加您对blackbox的处理逻辑
    if (callback) {
        callback(blackbox);
    }
  } forKey:@"callback"];
  riskManager->initWithOptions(options);

}

必传配置

配置 key 定义 说明 场景 示例代码
partner 合作方编码 同盾的合作方编码，请联系同盾运营获取 所有场景 Objective C [options setValue:@"请输入您的合作方编码" forKey:@"partner"]; Swift options.updateValue("请输入您的合作方编码" as NSObject, forKey: "partner")
appKey 应用标识 同盾生成的应用标识，和app绑定，用于校验app的有效性，请联系同盾运营获取 appkey创建需要用户提供应用包名、小写的sha256 签名。 ⚠️不同应用的包名签名不要使用相同的值 所有场景 Objective C [options setValue:@"请输入您的appKey" forKey:@"appKey"]; Swift options.updateValue("请输入您的appKey" as NSObject, forKey: "appKey")
appName 应用名称 同盾平台注册的应用名称，请联系同盾运营获取 所有场景 Objective C [options setValue:@"请输入您的appName" forKey:@"appName"]; Swift options.updateValue("请输入您的appName" as NSObject, forKey: "appName")
country 国家地区 国家地区参数，如cn sg us fra 根据国家地区填写对应参数。 cn代表中国， sg代表新加坡， us代表北美， fra代表欧洲 Objective C [options setValue:@"请输入您所在的国家地区" forKey:@"country"]; Swift options.updateValue("请输入您所在的国家地区" as NSObject, forKey: "country")

# 获取SDK版本号

示例代码

// 获取SDK版本号
TDMobRiskManager_t *riskManager = [TDMobRiskManager sharedManager];
NSString *sdkVersion = riskManager->getSDKVersion();

# 验证码功能模块

# initWithOptions选传参数

配置 key 定义 说明 场景 示例代码
language 语言类型 可选项： 1-简体中文、2-繁体中文、3-英 文、4-日文、5-韩文、6-⻢来语、7-泰语、8-印尼语、9-俄 语 默认： 1-简体中文 客户根据需要设置语言类型。 国内支持1-5 海外支持1-9 [options setValue:@"1" forKey:@"language"];
tapToClose 点击空白处是否关闭验证码 可选项： true、false 默认： false 开启后，点击界面空白处，会关闭验证码弹窗，关闭弹窗更加便捷 [options setValue:@(true) forKey:@"tapToClose"];
needSeqid 失败回调信息中是否携带seqid 可选项： true、false **默认：**true 开启后，失败信息中会携带seqid序列号，将seqid提供给同盾，方便排查失败原因 [options setValue:@(true) forKey:@"needSeqid"];
hideLoadHud 是否跳过加载动画 可选项： true、false **默认：**false 开启后，弹出验证码弹窗时不会再显示加载动画，缩短验证时间 [options setValue:@(true) forKey:@"hideLoadHud"];
hideWebCloseButton 是否隐藏webview的关闭按钮 可选项： true、false **默认：**false 需要强制完成验证码验证的场景 [options setValue:@(true) forKey:@"hideWebCloseButton"];
openLog 是否打开log 可选项： true、false **默认：**false 开启后，调试时控制台会输出更多的log信息，方便排查问题 [options setValue:@(true) forKey:@"openLog"];
skipCaptcha 是否跳过同盾验证码验证 可选项： true、false **默认：**false 开启将不会进行验证码的验证，同时返回4000错误码，用于动态设置是否使用同盾验证码SDK验证的场景 [options setValue:@(true) forKey:@"skipCaptcha"];
mfaId MFA产品 可选项： string **默认：**nil 如果您接入了MFA产品（未对接MFA，可忽略该说明），请将MFA流程中获取的 mfaid传递给验证码配置参数 [options setValue:@"mfaId string" forKey:@"mfaId"];

# 弹出验证码弹窗

showCaptcha函数

[TDMobRiskManager sharedManager]->showCaptcha 函数 用于显示验证码弹窗，其接口定义如下

// 显示验证码弹窗
// @param superView 弹窗显示在的父视图，UIView 类型
// @param block 结果回调的block
void (*showCaptcha)(id superView,TongdunShowCaptchaBlock block);

回调参数结构体TongdunShowCaptchaResultStruct

我们使用TongdunShowCaptchaResultStruct 结构体存储回调的结果；

typedef enum {
    // 验证码校验成功，此时可以获取到有效的 validateToken；
    TongdunShowCaptchaResultTypeSuccess,
    // 验证码校验失败，可以获取错误码 errorCode和errorMsg，根据文档中的`错误码`排查原因；
    TongdunShowCaptchaResultTypeFailed,
    // 验证码弹窗成功，等待被验证；
    TongdunShowCaptchaResultTypeReady,
} TongdunShowCaptchaResultType;


typedef struct _TongdunShowCaptchaResultStruct{
    // 返回的结果类型
    TongdunShowCaptchaResultType resultType;
    // 返回成功后，返回的验证码的token
    const char*validateToken;
    // 返回失败后，返回的错误码，可以根据文档排查原因
    NSInteger errorCode;
    // 返回失败后，返回的错误信息
    const char*errorMsg;
}TongdunShowCaptchaResultStruct;

示例代码

- (void)showCaptcha {
    UIWindow * keyWindow = [UIApplication sharedApplication].keyWindow;
    TDMobRiskManager_t *riskManager = [TDMobRiskManager sharedManager];
    riskManager->showCaptcha(keyWindow,^(TongdunShowCaptchaResultStruct resultStruct) {
        switch (resultStruct.resultType) {
            case TongdunShowCaptchaResultTypeSuccess:
            {
                NSString * validateToken = @(resultStruct.validateToken);
                NSLog(@"获取同盾验证码成功！！！,validateToken:%@",validateToken);
            }
                break;
            case TongdunShowCaptchaResultTypeFailed:
            {
                NSString * errorMsg = @(resultStruct.errorMsg);
                NSLog(@"获取同盾验证码失败！！！,errorCode:%ld,errorMsg:%@",resultStruct.errorCode,errorMsg);
            }
                break;
            case TongdunShowCaptchaResultTypeReady:
                NSLog(@"验证码弹窗成功，等待被验证！！！");
                break;
            default:
                break;
        }
    });
}

# 错误码

验证码功能模块的错误码会通过 showCaptcha 函数输出

错误码 错误信息 处理方式
1001 关闭了验证码窗口 弹出验证码后，用户手动取消了验证码，不需要处理
2001 请求参数异常，请检查参数 请检查appName和partnerCode参数
2100 请求参数异常，请检查参数 请检查传递参数
2101 请求参数异常，请检查参数 请求过程出错，请联系运营
2102 请求参数异常，请检查参数 参数缺失，请检查参数
2111 验证⻚面网络错误 稍后再试，或者请联系运营
2112 验证⻚面操作太频繁 稍后再试
2113 未知错误 未知错误，请联系运营
2114 关闭了验证码窗口 点击了验证码关闭按钮，不需要处理
2115 验证⻚面网络错误 网络资源加载失败
2116 验证⻚面网络错误 网络资源加载失败
2202 验证成功 验证结果成功，不需要处理
2301 未购买此服务 请联系运营
2302 流量已被禁用 请联系运营
2303 流量不足 请联系运营
2304 服务已过期 请联系运营
2305 日流量已封顶 请联系运营
2600 系统繁忙，请稍后再试 系统繁忙，请稍后再试
2601 验证失败，稍后重试 验证失败，请稍后重试
2602 验证失败，稍后重试 验证失败，请稍后重试
2603 验证失败，稍后重试 验证失败，请稍后重试
2604 验证失败，稍后重试 刷新频繁，请稍后重试
2605 验证失败，稍后重试 获取验证码信息失败
2702 验证失败，稍后重试 解析错误，请稍后重试
3001 SSL证书校验失败 请关闭网络代理工具
3002 验证页面加载出错 刷新网络后重试
3003 验证⻚面加载超时 检查网络后重试
4000 验证逻辑跳过 开发者手动处理验证跳过逻辑
9000 设备指纹没有挂载 集成验证码需要先集成设备指纹
9001 没有网络 请检查网络连接
9002 请求超时 检查网络，稍后重试
9003 返回结果异常 服务端错误，返回结果异常，联系技术支持
9004 全局加载超时 检查网络，稍后重试

# FAQ

Q1：引入终端SDK后，工程无法再进行 Xcode 调试，如何解决？

A1：请参考 SDK初始化 (opens new window) 在终端SDK初始化时，加入如下参数

[options setValue:@"allowed" forKey:@"allowed"];
: 2023/06/07 16:19:48

← Web →