Fraud Detection:Integrate the Device Risk SDK for iOS

Prerequisites

Before you begin, make sure you have:

• An iOS app targeting iOS 9.0 or later

• Xcode 12 or later (required for IDFA permission handling on iOS 14+)

• An app key from the Fraud Detection console — find it on the Device App Keys tab

Compliance requirements

Before using the SDK to collect device information, display the Fraud Detection SDK privacy policy and obtain explicit user consent. Do not assume users have agreed by default.

The privacy policy must disclose the following:

• SDK name: Device Fraud Detection SDK

• Purpose: Detection of abnormal devices such as tampered devices, emulators, and malicious scripts

• Privacy policy link: Fraud Detection SDK privacy policy

• Data collected:

  Category	Data points
  Basic device info	Device manufacturer, brand, type and model, name, OS information, memory and storage capacity, sensor list, battery and battery usage, baseband information, boot time, screen brightness and resolution, CPU information, system time zone, system language, charging status, and system kernel information
  Identification (required)	Identifier for vendors (IDFV)
  Identification (optional)	International Mobile Equipment Identity (IMEI), International Mobile Subscriber Identity (IMSI), MAC address, Integrated Circuit Card Identifier (ICCID), hardware serial number, identifier for advertisers (IDFA), Android device ID, Open Anonymous Device Identifier (OAID), Google advertising ID (AID), and Bluetooth MAC address
  Network info	IP address (optional), nearby Wi-Fi list (optional), Basic Service Set Identifier (BSSID) (optional), Service Set Identifier (SSID) (optional), carrier information, network type, network status, SIM card status, and network card information
  App info	App name, app version, installation time, and app list (optional)

Display the privacy policy when users start the app for the first time. Only start collecting device information after the user agrees. Avoid collecting device information at app startup unless required for a specific risk scenario — this prevents excessive or premature data collection.

Add Info.plist permissions

Add the following entries to your app's Info.plist before publishing to App Store. Missing entries may cause App Store review rejection.

Install and configure the SDK

1. Download Device Fraud Detection SDK for iOS from the Fraud Detection console. On the Device App Keys tab, click Download Device SDK. iOS SDK versions start with I.; Android SDK versions start with A..

   Note

   If the SDK version has an idfa suffix, the SDK can collect sensitive identifier information (IDFA). Check the SDK download list for details.

2. Copy deviceiOS.framework from the SDK package into your iOS project directory.

3. In Xcode, select your target, go to Build Phases > Link Binary With Libraries, and add deviceiOS.framework plus the following dependencies:

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

   

4. (Optional) Download the Objective-C demo package from the Developer Center page to use as a reference implementation.

Collect device data

Call initDevice as soon as possible in risk scenarios — for example, when the app launches or when a user reaches a registration or payment screen. The SDK is a SecurityDevice singleton.

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

Parameters

`options` parameters

Return value: none.

Get a device token

Obtain the client token and report it to your business server. Then, use server-side API operations to retrieve device threat information. For more information, see Device Fraud Detection events and response parameters.

After data collection succeeds, retrieve a token and pass it to your server. The server uses the token — along with event parameters — to query device risk information. For parameter and response details, see Service event parameters and response parameters for Device Fraud Detection.

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

Return value: a SecurityToken object.

@interface SecurityToken : NSObject

// Status code for the token retrieval call.
@property(atomic) int code;

// The token string to pass to your server.
@property(copy, atomic) NSString *token;

@end

Token timing guidelines

1. Call getDeviceToken only after initCallback returns 10000.

2. If you cannot wait for the initCallback result, wait at least 2 seconds after calling initDevice before calling getDeviceToken — data reporting may still be in progress.

3. Retrieve a new token each time you query device risk information. Tokens are valid for seven days.

Status codes

Sample code

The following example shows the complete integration flow: requesting IDFA permission on iOS 14+, initializing the SDK, and retrieving the token in a risk scenario such as account registration or a promotional activity.

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" withOptions:nil callback:^(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, request IDFA permission before initializing the SDK.
    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 risk scenarios — such as account registrations or promotional activities — retrieve the token and send it to your server:

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

// Send the token to your server and call the Device Fraud Detection operations.
// ...

What's next

Pass the deviceToken and event parameters to the Fraud Detection service:

• Service event parameters and response parameters for Device Fraud Detection