Fraud Detection:Integrate Device Risk Detection SDK for iOS

Prerequisites

The app into which you want to integrate Device Risk Detection SDK for iOS runs on iOS 9.0 or later.

Compliance terms

1. The app must post the privacy policy of Device Risk Detection SDK when users start the app for the first time. This helps obtain the consent from users to use Device Risk Detection SDK. Users must read and agree to the privacy policy before they proceed. Do not make an assumption that users read and agree to the privacy policy by default.

2. The privacy policy must inform users of the following items:

• SDK name: Device Risk Detection SDK

• Service type: detection of abnormal devices such as tampering devices, emulators, and malicious scripts.

• Device information to be collected:

  • Basic information: the manufacturer, brand, model, name, operating system, configurations, and environment information.

  • Identity information: the International Mobile Equipment Identity (IMEI), International Mobile Subscriber Identity (IMSI), MAC address, Integrated Circuit Card Identifier (ICCID), Android ID, hardware serial number, Open Anonymous Device Identifier (OAID), Google Advertising ID (Google AID), Bluetooth MAC address, Identifier for Advertisers (IDFA), and Identifier for Vendors (IDFV).

  • Network information: the IP address, Wi-Fi information, Basic Service Set Identifier (BSSID), Service Set Identifier (SSID), carrier, network type, and network status.

  • Other information: the information about the app that uses the SDK, such as the app name, app version, and app installation time.

3. Users must read and agree to the privacy policy before Device Risk Detection SDK is initialized.

Permissions

Before you publish the app to App Store, make sure that the fields and descriptions in the following table are added to the Info.plist file of the app. This improves the efficiency of fraud detection. If you do not add the fields or descriptions, the app may fail to be published to App Store.

Download and configure Device Risk Detection SDK for iOS

1. Download Device Risk Detection SDK for iOS and create an appkey in the Fraud Detection console. The SDK package is a standard static framework package for Xcode.

2. Copy the deviceiOS.framework file in the SDK package to the iOS project directory.

3. Select the target, click the Build Phases tab, and then add the following dependencies in the Link Binary With Libraries section:

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

4. Download the Objective-C Demo package.

Operation definition

Initialize the SDK

Initialize Device Risk Detection SDK. Make sure that Device Risk Detection SDK is initialized at the earliest opportunity after a user agrees to the privacy policy.

• Function

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

• Parameters

userAppKey: the identity of the user. You can obtain the identity on the Device APP management tab in the Fraud Detection console.

initCallback: the callback for initializing Device Risk Detection SDK. You can check whether the initialization is successful by using this callback. For more information about the value range of the code parameter, see the "Status codes" section of this topic.

• Response parameters

None.

Note: If the return value of the code parameter in the initCallback callback is not 10000, you can reinitialize the SDK until the SDK is initialized.

Obtain the token of the client

Obtain and send the client token to the business server. You can use the token to call the Device Risk Detection Fraud Detection API on the business server to obtain the device fingerprint information.

• Function

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

• Parameters

None.

• Response parameters

The value is a SecurityToken class.

code: the call status code of the operation. You can check whether the call is successful based on the status code. For more information about the value range of the code parameter, see the "Status codes" section of this topic.

token: the token that is returned to the client. The token can be used to call the Device Risk Detection Fraud Detection API.

@interface SecurityToken : NSObject

// The result of the operation that obtains the token.
@property(atomic) int code;

 // The token string.
@property(copy, atomic) NSString *token;

@end

Suggestions for obtaining the token:

1. Obtain the token if the initCallback callback returns 10000 for the code parameter.

2. If you do not want to wait for the return result of the initCallback callback after you call the initDevice operation, we recommend that you wait for at least 2 seconds before you call the getDeviceToken operation. This is due to possible latency issues in data reporting.

3. Obtain a new token when you need to query the device fingerprint information. The validity period of the token is seven days.

Status codes

Sample code

Initialize Device Risk Detection SDK for iOS. You must call the initDevice operation at the earliest opportunity when the app starts.

Note: The privacy policy of Apple stipulates that the use of the IDFA must be explained in the Info.plist file and a message must be displayed to ask for user consent to use the IDFA. Therefore, make sure that Xcode 12 or later is installed in the development environment.

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];
    
    // For iOS 14 and later, obtain the permissions to use the IDFA by using a pop-up dialog box. 
    if (@available(iOS 14, *)) {
        [self helperRequestIDFAPermissionWithBlock:^(bool success) {
            if (success) {
                NSLog(@"IDFA Permission OK.");
            } else {
                NSLog(@"No IDFA Permission.");
            }
            
            [self initSecurityDevice];
        }];
    } else {
        [self initSecurityDevice];
    }
}

In business scenarios in which fraud detection is required, such as account registrations and promotional activities, you must obtain the token of the client and submit the token to the business server. Then, you can query the device fingerprint information.

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

// Send the token to the self-managed business server and call the Device Risk Detection Fraud Detection API. 
// ...

Call the Device Risk Detection Fraud Detection API

Use the deviceToken parameter and other related parameters to call the Device Risk Detection Fraud Detection API. For more information, see the following topics:

Service event parameters and response parameters for Device Risk Detection Fraud Detection

The following figure shows the sequence diagram for integrating and using the SDK.

Note

Step 1 and Step 2 are required only if you load the SDK for the first time. You can perform Steps 3 through 9 in a loop based on your business requirements.