设备风险SDK iOS接入

前提条件

设备风险SDK需在iOS 9.0及以上的系统版本上运行。

合规条款

1、您需要确保App有《风险识别SDK隐私权政策》，并且在用户首次启动App时就弹出《风险识别SDK隐私权政策》取得用户同意，请勿默认客户已勾选。

2、您务必在《风险识别SDK隐私权政策》中向用户告知使用阿里云设备风险识别SDK，参考条款如下：

• 使用SDK名称：阿里云设备风险识别SDK；

• 服务类型：检测篡改设备、模拟器、恶意脚本等异常设备；

• 收集设备信息：当您使用风险识别产品且接入设备风险识别SDK服务时，为了检测最终用户的设备欺诈与作弊行为，识别设备的真实性，我们会获取最终用户的：

  • 设备基础信息：设备制造商、设备品牌、设备类型及型号、设备名称、设备操作系统信息、设备内存及存储大小、传感器列表、电池及电量信息、基带信息、开机时间、屏幕亮度及分辨率、CPU信息、系统时区、系统语言、充电状态、系统内核信息；

  • 设备标识信息（必要）：IDFV；

  • 设备标识信息（可选）：IMEI（国际移动识别码）、IMSI（国际移动用户识别码）、MAC地址、ICCID（集成电路卡识别码）、硬件序列号、IDFA、Android ID、OAID、Google AID（Google广告ID）、蓝牙MAC；

  • 设备网络信息：IP地址（可选）、附近WIFI列表（可选）、BSSID（可选）、SSID(可选)、运营商信息、网络类型、网络状态、SIM卡状态、网卡信息；

  • 设备应用信息：SDK宿主APP信息（包括：应用名称、应用版本、安装时间）、应用列表（可选）。

• 隐私政策链接：《风险识别SDK隐私权政策》。

3、您务必确保用户同意《风险识别SDK隐私权政策》之后，再使用阿里云设备风险识别SDK采集信息。如无必要，请勿在启动应用时采集设备信息，避免过度或过早采集。

权限说明

为增强风险识别效果，在App Store上架之前，请确认App已经在Info.plist中添加如下字段及说明信息，否则可能会导致上架失败。

下载及配置SDK

1、下载iOS SDK（SDK为XCode上标准静态framework包），并在下载SDK的控制台中生成AppKey。

2、将SDK包中的deviceiOS.framework复制到iOS工程目录下。

3、选择工程配置，定位到Build Phases -> Link Binary With Libraries，添加deviceiOS.framework及其依赖包：

AppTrackingTransparency.framework
CoreTelephony.framework
libresolv.tbd
Security.framework
AdSupport.framework
libz.tbd
libc++.tbd
deviceiOS.framework

4、下载Objective-C Demo包。（单击设备APP管理 > 下载设备SDK > 更多版本，安卓：A.demo，iOS：I.demo）。

5、请根据自身业务属性，选择是否带有idfa等敏感数据采集功能的SDK，具体参考SDK下载列表描述。

通过SDK采集数据

通过SDK采集数据，务必确保用户同意《风险识别SDK隐私权政策》之后，在风险场景尽早通过阿里云设备风险识别SDK采集数据。

• 函数原型

@interface SecurityDevice : NSObject
- (void)initDevice:(NSString *)userAppKey 
  	withOptions:(NSMutableDictionary *)options 
    callback:(void (^)(int))initCallback;
// ...
@end

• 参数

  • userAppKey：用于标识用户身份，可在阿里云控制台的设备App管理申请获取。

  • options：采集数据的可选项，默认可以为nil。可选参数如下：

initCallback：设备风险SDK采集数据回调接口，可在回调中判断采集数据是否成功。其中，Code字段取值范围可参考“状态返回值”。

返回值：无。

获取客户端Token

获取客户端Token，并上报到业务服务器，后续通过服务器端设备风险识别事件及返回参数，从而获取设备风险信息。

• 函数原型

@interface SecurityDevice : NSObject
// ...
- (SecurityToken *) getDeviceToken;
@end

参数：无。

返回值：SecurityToken类型。

• Code：返回接口调用状态码，可用于判断接口调用是否成功。Code字段取值范围可参考“状态返回值”。

• Token：返回客户端Token字符串信息，可用于业务后续查询阿里云设备风险识别接口。

@interface SecurityToken : NSObject

// 获取 token 操作的结果
@property(atomic) int code;

 // token 字符串
@property(copy, atomic) NSString *token;

@end

Token获取时机建议：

1、在initDevice接口的callback返回10000的时候获取；

2、如果不等待initDevice的callback返回，我们建议initDevice接口和getDeviceToken接口口调用时间能间隔2秒以上；（因为数据上报可能存在延迟）

3、每次在需要风险查询的时候，重新获取Token，Token的有效期为7天。

状态返回值

示例代码

设备风险识别SDK采集数据，initDevice接口需要在各种风险场景中尽可能早的时候调用。

typedef void (^IDFARequestBlock)(bool success);

API_AVAILABLE(ios(14))
static bool isATTrackingEnabled(ATTrackingManagerAuthorizationStatus status) {
    if (ATTrackingManagerAuthorizationStatusAuthorized == status) {
        return true;
    }
    return false;
}

- (void)helperRequestIDFAPermissionWithBlock:(IDFARequestBlock) complete {
    if (@available(iOS 14, *)) {
        ATTrackingManagerAuthorizationStatus authStatus = ATTrackingManager.trackingAuthorizationStatus;
        if (ATTrackingManagerAuthorizationStatusNotDetermined == authStatus) {
            [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
                if (nil != complete) {
                    return complete(isATTrackingEnabled(status));
                }
            }];
        } else if (nil != complete) {
            return complete(isATTrackingEnabled(authStatus));
        }
    }
}

- (void)initSecurityDevice {
    SecurityDevice *securityDevice = [SecurityDevice sharedInstance];
    [securityDevice initDevice: @ "ALIYUN_APPKEY": ^ (int code) {
        NSString * initResult = [NSString stringWithFormat: @ "init code: %d", code];
        NSLog(@ "%@", initResult);
        if (10000 != code) {
            NSLog(@ "init error.");
        } else {
            NSLog(@ "init success");
        }
    }];
}

- (void)viewDidLoad {
    [super viewDidLoad];
    
    // iOS 14及以上系统需要用户弹框获取 IDFA 权限。
    if (@available(iOS 14, *)) {
        [self helperRequestIDFAPermissionWithBlock:^(bool success) {
            if (success) {
                NSLog(@"IDFA Permission OK.");
            } else {
                NSLog(@"No IDFA Permission.");
            }
            
            [self initSecurityDevice];
        }];
    } else {
        [self initSecurityDevice];
    }
}

在业务需要风险识别的场景下（如注册、活动推广等）获取户端Token，并上报到业务的服务器端进行风险查询。

SecurityDevice *securityDevice = [SecurityDevice sharedInstance];
SecurityToken * deviceToken = [securityDevice getDeviceToken];
NSString * rs = [NSString stringWithFormat: @ "[%d]%@", deviceToken.code, deviceToken.token];
NSLog(@ "deviceToken: %@", rs);

// 发送token到业务自有服务器并查询阿里云设备风险识别接口。
// ...

调用风险识别API接口

将deviceToken与其他参数，根据如下相应的风险识别服务事件参数文档说明，请求风险识别API接口进行识别：

注册风险识别功能及参数说明

营销风险识别-增强版事件及返回参数

登录风险识别功能及参数说明

设备风险识别事件及返回参数