Fraud Detection：裝置風險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介面進行識別：

裝置風險識別事件及返回參數