iOS

Integrated Requirement

Compliance Explanation

Please note that when integrating SDK products provided by the TrustDecision in the APP of your company:

1.1 According to the user's information protection regulations, before your users start the App for the first time and start collecting information, your company should fully inform the user of the purpose, method, and scope of collecting, using, and sharing the user's personal information with a third party through an interactive interface or design (such as a pop-up window of the privacy policy), and obtain the express consent of the end user.

1.2 To provide business security and risk control services to your company, the TrustDecision SDK will collect, process, and use the identification information(IMEI/IDFA), AndroidID, IMSI, MEID, MAC address, SIM card serial number, device type, device model, system type, geographical location, login IP address, application list, running process, sensor information(light sensor, gravity sensor, magnetic field sensor, acceleration sensor, gyroscope sensor) and other device information of the user's device. To ensure compliance with your use of related services, the aforementioned privacy policy should cover the authorization of TrustDecision SDK to provide services and collect, process, and use relevant information. The following terms are for your reference. The specific expression can be determined by your company according to the overall framework and content of your privacy agreement:

TrustDecision SDK: For business security and risk control, our company uses the TrustDecision SDK. The SDK needs to obtain the information of your devices, such as (IMEI/IDFA), AndroidID, IMSI, MAC address, SIM card serial number, device type, device model, system type, geographic location, login IP address, application list, running process, sensor information(light sensor, gravity sensor, magnetic field sensor, acceleration sensor, gyroscope sensor) and other related device information, for fraud risk identification.

Privacy Protocol: https://www.trustdecision.com/legal/privacy-policy

Environment

ItemsDescription
Supported System VersionsiOS9.0+
Supporting architecturearmv7, arm64, x86_64

Integrate Steps

CocoaPods

SDK access sample code : https://github.com/trustdecision/mobrisk-ios-sample

  • Added pod 'TrustDecisionPro', '4.2.6.4' in the corresponding target in the Podfile
  • Added pod 'TrustDecisionCaptcha', '2.1.8.4' in the corresponding target in the Podfile
  • Execute the pod install --repo-update command in the folder where the Podfile is located. (M1 series mac computers need to execute arch -x86_64 pod install --repo-update command)

SDK Structure

files in Pods/TrustDecisionPro directory:

  • TDMobRisk.framework(TrustDecision SDK, is a static library type)
  • TDCorePlugin.framework (TrustDecision plugin, is an Embed dynamic library type)

files in Pods/TrustDecisionCaptcha directory:

  • libTDCaptcha.a(Mob-Risk SDK captcha component library, is a static library type)
  • TDCaptchaResource.bundle (Mob-Risk SDK captcha component Required resource package)

Import Header File

Please import the header file if you want to call SDK API.

#import <TDMobRisk/TDMobRisk.h>
import TDMobRisk

App Privacy Configuration

According to the latest App Store Privacy Policy announced by Apple, starting from the spring of 2024, apps listed on the App Store will need to carry an App privacy list document.
Starting May 1, 2024, App Store Connect will not accept apps that do not describe their use of the required reason API in a privacy manifest file.

Adaptation Steps

Please choose a solution based on your actual situation.

  1. If the PrivacyInfo.xcprivacy file does not exist in the project directory
  • Create a new App Privacy type file through Xcode in the project directory, name it PrivacyInfo, and check the required Targets
  • Select the PrivacyInfo.xcprivacy file in the project directory and right-click to open the menu. Open the file through Open As -> Source Code in the menu
  • Paste the SDK's PrivacyInfo.xcprivacy below into the PrivacyInfo.xcprivacy file in the project directory
  1. If the PrivacyInfo.xcprivacy file already exists in the project directory
  • Select the PrivacyInfo.xcprivacy file in the project directory and right-click to open the menu. Open the file through Open As -> Source Code in the menu.
  • Added content in the PrivacyInfo.xcprivacy file in the project directory that is mentioned in SDK's PrivacyInfo.xcprivacy but is still missing in the project directory PrivacyInfo.xcprivacy file

SDK's PrivacyInfo.xcprivacy

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>NSPrivacyCollectedDataTypes</key>
	<array>
		<dict>
			<key>NSPrivacyCollectedDataType</key>
			<string>NSPrivacyCollectedDataTypeDeviceID</string>
			<key>NSPrivacyCollectedDataTypeLinked</key>
			<true/>
			<key>NSPrivacyCollectedDataTypeTracking</key>
			<false/>
			<key>NSPrivacyCollectedDataTypePurposes</key>
			<array>
				<string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
				<string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
			</array>
		</dict>
	</array>
	<key>NSPrivacyAccessedAPITypes</key>
	<array>
		<dict>
			<key>NSPrivacyAccessedAPIType</key>
			<string>NSPrivacyAccessedAPICategoryDiskSpace</string>
			<key>NSPrivacyAccessedAPITypeReasons</key>
			<array>
				<string>E174.1</string>
			</array>
		</dict>
		<dict>
			<key>NSPrivacyAccessedAPIType</key>
			<string>NSPrivacyAccessedAPICategoryUserDefaults</string>
			<key>NSPrivacyAccessedAPITypeReasons</key>
			<array>
				<string>CA92.1</string>
			</array>
		</dict>
		<dict>
			<key>NSPrivacyAccessedAPIType</key>
			<string>NSPrivacyAccessedAPICategorySystemBootTime</string>
			<key>NSPrivacyAccessedAPITypeReasons</key>
			<array>
				<string>35F9.1</string>
			</array>
		</dict>
	</array>
</dict>
</plist>

Initialization

Precautions

When the installation starts for the first time, the SDK initialization is performed after the user agrees with the privacy agreement.

Avoid SDK initialization collection without the user agreeing to the privacy agreement, causing compliance risk accidents.

Interface Definition

void (*initWithOptions)(NSDictionary *options);

initWithOptions method Required Configuration

Key Definition Description Scene Sample code
partner Partner code Partner, please contact TrustDecision to obtain All Scenes Objective C
[options setValue:@"[Your partner]" forKey:@"partner"];
Swift
options.updateValue("[Your partner]" as NSObject, forKey: "partner")
appKey App key Appkey, please offer your App bundleId for TrustDecision to obtain.
appkey creation requires the user to provide the application bundleId
All Scenes Objective C
[options setValue:@"[Your appKey]" forKey:@"appKey"];
Swift
options.updateValue("[Your appKey]" as NSObject, forKey: "appKey")
appName App name AppName, please contact TrustDecision to obtain All Scenes Objective C
[options setValue:@"[Your appName]" forKey:@"appName"];
Swift
options.updateValue("[Your appName]" as NSObject, forKey: "appName")
country Country code Country/region parameters, such as cn sg us fra idna Fill in the corresponding parameters according to country and region of business.
cn means China,
sg means Singapore,
us means North America,
fra means Europe,
idna means Indonesia
Objective C
[options setValue:@"[Your country code]" forKey:@"country"];
Swift
options.updateValue("[Your country code]" , forKey: "country")

Sample Code

- (void)initTrustDecisionSDK {
  // Get riskManager
  TDMobRiskManager_t *riskManager = [TDMobRiskManager sharedManager];
  // Initialization Configuration
  NSMutableDictionary *options = [NSMutableDictionary dictionary];

/*************************** Mandatory Parameter ***************************/
  //Partner code, Refer to `Required Configuration`
  [options setValue:@"[Your partner]" forKey:@"partner"];
  //App key, Refer to `Required Configuration`
  [options setValue:@"[Your appKey]" forKey:@"appKey"];
  //App name, Refer to `Required Configuration`
  [options setValue:@"[Your appName]" forKey:@"appName"];
  //Country code, Refer to `Required Configuration`
  [options setValue:@"[Your country code]" forKey:@"country"];

  /*************************** Optional Parameter ***************************/
#ifdef DEBUG
  // !!! If not set this parameter in DEBUG mode, the app will terminate
  [options setValue:@(YES) forKey:@"allowed"];
#endif
  // !!!The callback method has been removed, and now a getBlackBoxAsync method has been added to asynchronously obtain blackbox
  riskManager->initWithOptions(options);
}
func initTrustDecisionSDK() {
  let riskManager = TDMobRiskManager.sharedManager()
  var options = [String : NSObject]()
  /*************************** Mandatory Parameter ***************************/
  // Partner code, Refer to `Required Configuration`
  options.updateValue("[Your partner]" as NSObject, forKey: "partner")
  // App key, Refer to `Required Configuration`
  options.updateValue("[Your appKey]" as NSObject, forKey: "appKey")
  // App name, Refer to `Required Configuration`
  options.updateValue("[Your appName]" as NSObject, forKey: "appName")
  // Country code, Refer to `Required Configuration`
  options.updateValue("[Your country]" as NSObject, forKey: "country")

   /*************************** Optional Parameter ***************************/
#if DEBUG
  // !!! If not set this parameter in DEBUG mode, the app will terminate
  options.updateValue(true, forKey: "allowed")
#endif
  // !!!The callback method has been removed, and now a getBlackBoxAsync method has been added to asynchronously obtain blackbox
 riskManager?.pointee.initWithOptions(options)
}

initWithOptions method Optional Parameter

Key Definition Description Scene Sample code
language language type Options: 1-Simplified Chinese, 2-Traditional Chinese, 3-English, 4-Japanese, 5-Korean, 6-Malay, 7-Thai, 8-Indonesian, 9-Russian
Default: 1-Simplified Chinese
You can set the language type according to your needs, Chinese mainland support 1-5, overseas support 1-9 Objective C
[options setValue:@"1" forKey:@"language"];
Swift
options.updateValue("1", forKey: "language")
tapToClose Click on the blank space to close the Captcha window Optional: true, false
Default: false
After opening, click on the blank area of the interface to close the Captcha window, which is more convenient to close the pop-up window Objective C
[options setValue:@(true) forKey:@"tapToClose"];
Swift
options.updateValue(true, forKey: "tapToClose")
needSeqid Whether to carry the seqid in the failure callback message Optional: true, false
Default: true
When enabled, the seqid serial number will be carried in the failure message, provide TrustDecision with seqId to facilitate troubleshooting Objective C
[options setValue:@(YES) forKey:@"needSeqid"];
Swift
options.updateValue(true, forKey: "needSeqid")
hideLoadHud Whether to skip the loading animation Options: true, false
Default: false
When enabled, the loading animation will not be displayed when the Captcha window pops up, shortening the verification time [options setValue:@(YES) forKey:@"hideLoadHud"];
Swift
options.updateValue(true, forKey: "hideLoadHud")
hideWebCloseButton Whether to hide the close button of the webview Options: true, false
Default: false
Scenarios that need to be forced to complete the Captcha Objective C
[options setValue:@(YES) forKey:@"hideWebCloseButton"];
Swift
options.updateValue(true, forKey: "hideWebCloseButton")
openLog Whether to open the log Options: true, false
Default: false
When enabled, the console will output more log information during debugging, which is convenient for troubleshooting Objective C
[options setValue:@(YES) forKey:@"openLog"];
Swift
options.updateValue(true, forKey: "openLog")
skipCaptcha Whether to skip the TrustDecision Captcha verification Options: true, false
Default: false
When enabled, the Captcha will not be verified, and a 4000 error code will be returned at the same time, which is used for dynamic settings Whether to use TrustDecision Captcha SDK verification Objective C
[options setValue:@(YES) forKey:@"skipCaptcha"];
Swift
options.updateValue(true, forKey: "skipCaptcha")
mfaId MFA ID Optional: string
Default: nil
If you have connected to the MFA product (the description can be ignored if the MFA is not connected), please set the mfa_id which is obtained from the MFA process to the configuration parameter. Objective C
[options setValue:@"mfaId string" forKey:@"mfaId"];
Swift
options.updateValue("mfaId string", forKey: "mfaId")

Popup Captcha Window

showCaptcha method

The showCaptcha method is used to display the Captcha window, and its interface is defined as follows

// Display Captcha window
// @param superView The parent view where the popup is displayed, UIView type
// @param block result callback block
void (*showCaptcha)(id superView,TDShowCaptchaBlock block);

Callback parameter structure TDShowCaptchaResultStruct

We use the TDShowCaptchaResultStruct structure to store the result of the callback;

typedef enum {
    // The Captcha is verified successfully, and a valid validateToken can be obtained at this time;
    TDShowCaptchaResultTypeSuccess,
    // If the Captcha fails, you can get the error code errorCode and errorMsg, and check the cause according to the `Error code` in the document;
    TDShowCaptchaResultTypeFailed,
    // The Captcha window pop-up is successful, waiting to be verified;
    TDShowCaptchaResultTypeReady,
} TDShowCaptchaResultType;


typedef struct _TDShowCaptchaResultStruct{
    // return result type
    TDShowCaptchaResultType resultType;
    // After returning successfully, the token of the Captcha returned
    const char*validateToken;
    // After the return fails, the returned error code can be checked according to the document
    NSInteger errorCode;
    // Return error message after failure
    const char*errorMsg;
}TDShowCaptchaResultStruct;

Example Code

- (void)showCaptcha {
    UIWindow * keyWindow = [UIApplication sharedApplication].keyWindow;
    TDMobRiskManager_t *riskManager = [TDMobRiskManager sharedManager];
    riskManager->showCaptcha(keyWindow,^(TDShowCaptchaResultStruct resultStruct) {
        switch (resultStruct. resultType) {
            case TDShowCaptchaResultTypeSuccess:
            {
                NSString * validateToken = resultStruct.validateToken;
                NSLog(@"Obtain TrustDecision Captcha successfully!!!,validateToken:%@",validateToken);
            }
                break;
            case TDShowCaptchaResultTypeFailed:
            {
                NSString * errorMsg = resultStruct. errorMsg;
                NSLog(@"Get TrustDecision Captcha failed!!!, errorCode:%ld, errorMsg:%@",resultStruct.errorCode,errorMsg);
            }
                break;
            case TDShowCaptchaResultTypeReady:
                NSLog(@"Captcha window popup is successful, waiting to be verified!!!");
                break;
            default:
                break;
        }
    });
}
func showCaptcha() {
    let keyWindow = UIApplication.shared.keyWindow
    let riskManager = TDMobRiskManager.sharedManager()
    riskManager?.pointee.showCaptcha(keyWindow) { (resultStruct : TDShowCaptchaResultStruct!)->Void  in
        switch resultStruct.resultType {
        case TDShowCaptchaResultTypeSuccess:
            let validateToken = String(cString:resultStruct.validateToken)
            print("Obtain TrustDecision Captcha successfully!!!,validateToken:\(validateToken)")
        case TDShowCaptchaResultTypeFailed:
            let errorMsg = String(cString:resultStruct.errorMsg)
            print("Get TrustDecision Captcha failed!!!,errorCode:\(resultStruct.errorCode),errorMsg:\(errorMsg)")
        case TDShowCaptchaResultTypeReady:
            print("Captcha window popup is successful, waiting to be verified!!!")
        default:
            break
        }
    }
}

Error Code

The error code of the captcha function module will be output through [TDMobRiskManager sharedManager]->showCaptcha method

Error codeError messageProcessing method
1001The Captcha window is closedAfter the Captcha window popup, the user manually cancels the Captcha, no processing is required
2001The request parameter is abnormal, please check the parameterPlease check the appName and partnerCode parameters
2100The request parameter is abnormal, please check the parameterPlease check the passed parameter
2101The request parameter is abnormal, please check the parameterThere is an error in the request process, please contact the operator
2102The request parameter is abnormal, please check the parameterThe parameter is missing, please check the parameter
2111Authentication page network errorTry again later, or please contact the operator
2112Verification page operation is too frequentTry again later
2113Unknown errorUnknown error, please contact the operator
2114Closed the Captcha windowClicked the Captcha close button, no need to process
2115Authentication page network errorFailed to load network resources
2116Authentication page network errorFailed to load network resources
2202Verification succeededThe verification result is successful and no processing is required
2301Did not purchase this servicePlease contact the operator
2302Traffic has been disabledPlease contact the operator
2303Insufficient trafficPlease contact the operator
2304Service has expiredPlease contact the operator
2305Daily traffic has been cappedPlease contact the operator
2600The system is busy, please try again laterThe system is busy, please try again later
2601Authentication failed, try again laterAuthentication failed, please try again later
2602Authentication failed, try again laterAuthentication failed, please try again later
2603Authentication failed, try again laterAuthentication failed, please try again later
2604Authentication failed, try again laterRefresh frequently, please try again later
2605Verification failed, try again laterFailed to obtain Captcha information
2702Authentication failed, try again laterParsing error, please try again later
3001SSL certificate verification failedPlease close the network proxy tool
3002Error loading verification pageRefresh the network and try again
3003Authentication page load timed outCheck network and try again
4000Validation logic skippingDevelopers manually handle validation skipping logic
9000The device fingerprint is not mountedTo integrate the Captcha, you need to integrate the device fingerprint first
9001No networkPlease check network connection
9002Request timed outCheck network, try again later
9003Return result is abnormalServer error, return result is abnormal, contact technical support
9004Global loading timed outCheck network, try again later

Get SDK Version

Sample Code

// Get SDK Version
TDMobRiskManager_t *riskManager = [TDMobRiskManager sharedManager];
NSString *sdkVersion = riskManager->getSDKVersion();
// Get SDK Version
let riskManager = TDMobRiskManager.sharedManager()
let sdkVersion = riskManager?.pointee.getSDKVersion()

FAQ

Q1: After integrated the TrustDecision SDK, the project can no longer be debugged in Xcode. How to solve it?

A1: Please refer to Initialization when initializing TrustDecision SDK, add the following parameters

[options setValue:@(YES) forKey:@"allowed"];
options.updateValue(true, forKey: "allowed")