This topic describes how to integrate Device Fraud Detection SDK for iOS
Prerequisites
Device Fraud Detection SDK for iOS requires iOS 9.0 or later.
Compliance terms
1. The app must post the Fraud Detection SDK privacy policy when users start the app for the first time. This helps obtain the consent from users to use Fraud 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 Fraud Detection SDK
Service scope: detection of abnormal devices such as tampering devices, emulators, and malicious scripts.
Device information to be collected: When you use Fraud Detection and integrate Device Fraud Detection SDK, the following information from users is required to detect fraudulent and cheating behavior, and verify the authenticity of their devices:
Basic information: device manufacturer, device brand, device type and model, device name, device operating system information, device memory and storage capacity, sensor list, battery and battery usage information, baseband information, boot time, screen brightness and resolution, CPU information, system time zone, system language, charging status, and system kernel information.
Identification information (required): identifier for vendors (IDFV).
Identification information (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.
Network information: IP address (optional), nearby WIFI list (optional), basic service set identifier (BSSID), service set identifier (SSID), carrier information, network type, network status, SIM card status, and network card information. BSSID and SSID are optional.
App information: the information about the app into which the SDK is integrated, including the app name, app version, and installation time, and the app list (optional).
Privacy policy link: Fraud Detection SDK privacy policy.
3. Make sure that users agree to the privacy policy before Device Fraud Detection SDK is used to collect information. If not necessary, do not collect device information when you start the app to prevent excessive or premature data collection.
Permission description
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.
Permission | Required | Description |
NSLocalNetworkUsageDescription | No (We recommend that you grant this permission to Device Fraud Detection SDK.) | The permission to obtain the connectivity of devices within a local area network (LAN) to discover risks such as device farms and group control. |
NSUserTrackingUsageDescription | No | The permission to obtain the IDFA of the device. This ensures that the ID of the device can always be obtained after operations are performed on the device. |
Download and configure Device Fraud Detection SDK
1. Download Device Fraud Detection SDK for iOS and create an app key in the Fraud Detection console. The SDK package is a standard static framework package for Xcode. For more information about how to download Device Fraud Detection SDK for iOS, go to the Fraud Detection console.
2. Copy the deviceiOS.framework file in the SDK package to the iOS project directory.
3. Select the required project, choose Build Phases > Link Binary With Libraries, and then add deviceiOS.framework and the dependencies.
AppTrackingTransparency.framework
CoreTelephony.framework
libresolv.tbd
Security.framework
AdSupport.framework
libz.tbd
libc++.tbd
deviceiOS.framework
4. Download the Objective-C Demo package at the Developer Center page. On the Device App Keys tab, click Download Device SDK. On the page that appears, download the SDK. The version of SDK for Android starts with A., and the version of SDK for iOS starts with I.
5. Select an SDK based on your business requirements. If the SDK version has the idfa
suffix, sensitive information can be collected. For more information, see the SDK download list.
Collect data by using Device Fraud Detection SDK
To collect data by using Device Fraud Detection SDK, make sure that users agree to the privacy policy. In risk scenarios, collect data by using Device Fraud Detection SDK at the earliest opportunity.
Function
@interface SecurityDevice : NSObject
- (void)initDevice:(NSString *)userAppKey
withOptions:(NSMutableDictionary *)options
callback:(void (^)(int))initCallback;
// ...
@end
Parameters
userAppKey: the identity of the user. You can obtain the identity on the Device App Keys tab in the Fraud Detection console.
options: the optional parameters for collecting data. The default value can be
nil
. The following table describes the optional parameters.
Parameter | Description | Example |
IPv6 | Specifies whether to use IPv6 domain names to report device information. Valid values: 0 (default value): Use IPv4 domain names. 1: Use IPv6 domain names. | "1" |
CustomUrl | The domain name of the self-managed server to which you want to report data. | "https://cloudauth-device.aliyuncs.com" |
CustomHost | The host for the self-managed server to which you want to report data. | "cloudauth-device.aliyuncs.com" |
initCallback: the callback operation for data collection by using Device Fraud Detection SDK, which can be used to determine whether data is collected. For more information about the value range of the Code
parameter, see the "HTTP status codes" section of this topic.
Return value: none.
Note: If the value of the Code
parameter returned by initCallback is not 10000, you can call the initDevice operation to collect data in subsequent operations until the data collection is successful.
Obtain a client token
Obtain a client token, report the token to the server, and then obtain the device risk information based on the event parameters and response parameters. For more information, see Service event parameters and response parameters for Device Fraud Detection.
Function
@interface SecurityDevice : NSObject
// ...
- (SecurityToken *) getDeviceToken;
@end
Input: none.
Return value: 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 theCode
parameter, see the "Status codes" section of this topic.Token
: the token that is returned to the client. Thetoken
can be used to call Device Fraud Detection operations.
@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 initDevice callback returns 10000 for the Code parameter.
2. If you do not want to wait for the return result of the initDevice 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
each time you want to query device risk information. The validity period of the token
is seven days.
HTTP status codes
Code | Description |
10000 | The data collection is successful. |
10001 | The data collection fails. |
10002 | The basic permissions required by the SDK have not been fully authorized. |
10003 | An unknown system error occurred. |
10004 | A network error occurred. |
10005 | A network error occurred, and the return value is an empty string. |
10006 | The format of the response is invalid. |
10007 | The system failed to parse the server settings. |
10008 | Internal data collection is not complete. |
Sample code
If you use Device Fraud Detection SDK to collect data, you must call the initDevice operation at the earliest opportunity in risk scenarios.
The privacy policy of Apple stipulates that the use of the IDFA must be explained in the 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 server. Then, you can query the device risk 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 server and call the Device Fraud Detection operations.
// ...
Call the Device Fraud Detection operations
Use the deviceToken
parameter and other related parameters to call Device Fraud Detection operations. For more information, see the following topics:
Service event parameters and response parameters for Device Fraud Detection