设备风险SDK iOS接入

本文介绍了阿里云设备指纹iOS SDK接入流程。

前提条件

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

合规条款

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

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

  • 使用SDK名称:阿里云设备风险识别SDK;

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

  • 收集设备信息:

    • 设备基础信息:设备制造商、设备品牌、设备型号、设备名称、设备操作系统信息、设备配置信息、设备环境信息;

    • 设备标识信息:IMEI(国际移动设别码)、IMSI(国际移动用户识别码)、MAC地址、ICCID(集成电路卡识别码)、AndroidId、硬件序列号、OAID、Google AID(Google广告ID)、蓝牙MAC、IDFA、IDFV;

    • 设备网络信息:IP地址、WIFI信息、BSSID、SSID、网络运营商信息、网络类型、网络状态;

    • 其他信息:SDK宿主APP信息(包括:应用名称、应用版本、安装时间);

  • 隐私政策链接:https://terms.aliyun.com/legal-agreement/terms/suit_bu1_ali_cloud/suit_bu1_ali_cloud202111120818_92724.html

3、您务必确保用户同意《隐私政策》之后,再初始化阿里云设备风险识别SDK。

权限说明

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

权限

是否必选

备注

NSLocalNetworkUsageDescription

否(推荐赋予)

获取局域网内设备连通性,用于发现设备牧场、群控等风险。

NSUserTrackingUsageDescription

用于获取 IDFA 信息,增强设备ID稳定性。

下载和配置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
iOS SDK

4、下载 Objective-C Demo 包。(点击“设备APP管理”-“下载设备SDK”-“更多版本”,安卓:A.demo,iOS:I.demo)

初始化 SDK

完成 SDK 内部初始化。务必确保用户同意《隐私政策》之后,尽早的初始化阿里云设备风险识别 SDK。

  • 函数原型

@interface SecurityDevice : NSObject
- (void)initDevice:(NSString *)userAppKey :(void (^)(int))initCallback;
// ...
@end
  • 参数

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

initCallback:设备风险 SDK 初始化回调接口,可在回调中判断初始化是否成功。其中,code 字段取值范围可参考“状态返回值”。

  • 返回值

无。

注意:当initCallback 回调的 code 值返回不为 10000 的时候,可以在 App 后续的逻辑中重新调用 initDevice 接口进行初始化,直到成功为止。

获取客户端 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 天。

状态返回值

Code

说明

10000

SDK 初始化成功

10001

SDK 未初始化

10002

SDK 需要的基础权限未完全授权

10003

系统未知错误

10004

网络错误

10005

网络错误,返回内容为空串

10006

网络返回的格式非法

10007

服务端配置解析失败

10008

内部初始化未完成

示例代码

初始化设备风险识别 SDK,initDevice接口需要在 App 启动尽可能早的时候调用。

注意:根据苹果官方隐私政策规定,IDFA 的使用除了在 plist 中做相关说明之后,需要调用方主动弹框提示用户授权,因此开发环境需要确保是 Xcode 12 以上。

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接口进行识别:

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

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

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

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

接入和使用时序图如下:

说明

其中第1和2步骤仅首次加载需要调用,第3~9步骤可以根据业务情况循环发起。

调用风险接口
阿里云首页 风险识别 相关技术圈