全部产品
Search
文档中心

风险识别:设备风险SDK iOS接入

更新时间:Nov 20, 2023

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

前提条件

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

合规条款

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

2、您务必在《隐私政策》中向用户告知使用阿里云设备风险识别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信息(包括:应用名称、应用版本、安装时间)、应用列表(可选)。

  • 隐私政策链接: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)

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

通过SDK采集数据

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

  • 函数原型

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

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

options:采集数据的可选项,默认可以为nil。可选参数如下:

字段名

说明

示例

IPv6

是否使用IPv6域名上报设备信息。

默认为“0”:使用IPv4域名;

“1”:使用IPv6域名。

"1"

CustomUrl

设置自有数据上报服务器域名

"https://cloudauth-device.aliyuncs.com"

CustomHost

设置自有数据上报服务器host

"cloudauth-device.aliyuncs.com"

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接口需要在各种风险场景中尽可能早的时候调用。

注意:根据苹果官方隐私政策规定,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接口进行识别:

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