iOS
Overview and Resources
The GeelabGuard iOS SDK is provided for developers integrating native iOS clients. The SDK does not depend on any third-party libraries.
Environment Requirements
| Item | Resource |
|---|---|
| Target Platform | Compatible with iOS 9+ |
| Development Environment | Xcode 13.0+ |
| System Dependencies | None |
| SDK Third-Party Dependencies | None |
Installation
Obtain the SDK
Please log in to the console to download it.
Import the SDK
-
If you add the SDK manually, drag the downloaded
GeelabGuardSDK.xcframeworkfile into your project and make sureCopy items if neededis checked.Import the xcframework via
Linked Frameworks and Libraries. After draggingGeelabGuardSDK.xcframeworkinto the project, verify that the.xcframeworkhas been added underPROJECT -> Build Phases -> Linked Frameworks and Libraries. -
For
Categorysymbols inside the static library, add-ObjCtoBuild Settings->Other Linker Flagsfor the corresponding target. -
The Geelab Device Fingerprint iOS SDK uses some of these APIs to obtain disk capacity and device/runtime environment signals for fraud detection. This involves the
NSPrivacyAccessedAPICategoryDiskSpaceandNSPrivacyAccessedAPICategoryFileTimestampcategories.
Apple announced a new privacy policy for applications, including SDKs, at WWDC23. See Get started with privacy manifests - WWDC23 - Videos - Apple Developer. Apple also published a related news update on July 27 stating that beginning in fall 2023, if a newly uploaded app uses relevant APIs without providing a privacy manifest, you will receive an email notice. Starting in spring 2024, the privacy manifest becomes mandatory. For the APIs involved and acceptable usage reasons, refer to Describing use of required reason API | Apple Developer Documentation. If your reason is not listed, you may also submit your specific justification directly. For instructions on creating a new privacy manifest, refer to Privacy manifest files | Apple Developer Documentation.
Code Examples
Import Header Files
Import the headers of the verification dynamic framework GeelabGuardSDK.framework into your project.
#import <GeelabGuardSDK/GeelabGuardSDK.h>Register the appID Immediately After App Launch and Configure Server Region
serverURLmust match the Region configured for your App ID in the dashboard.
| Region | serverURL |
|---|---|
| 🌏 Global(Default) | https://riskct-global.geelabapi.com/api/v2/client_report |
| 🇪🇺 Europe | https://riskct-eu.geelabapi.com/api/v2/client_report |
| 🇺🇸 North America | https://riskct-na.geelabapi.com/api/v2/client_report |
// Global server, default
GeelabGuard.register(withAppID: appID)
// Specify the service URL if needed
// GeelabGuard.register(withAppID: appID, serverURL: serverURL)// Use the public_key generated from your console account
#define APPID @"abcdef123456********ef1234567890"
// Specify the service URL if needed
// Global server, preconfigured in SDK
#define SubmitServerURL @"https://riskct-global.geelabapi.com/api/v2/client_report"
// Europe
// #define SubmitServerURL @"https://riskct-eu.geelabapi.com/api/v2/client_report"
// North America
// #define SubmitServerURL @"https://riskct-na.geelabapi.com/api/v2/client_report"
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Register your AppID, using global server
[GeelabGuard registerWithAppID:APPID];
// Using servers in other regions
// [GeelabGuard registerWithAppID:APPID serverURL:SubmitServerURL];
return YES;
}Get respondedGeeToken
Use GeelabGuardSDK to sign data and obtain a device-environment GeeToken:
// Optional, can be nil
let signData = "A unique serial number or credential for this business request, used for business association and verification".data(using:.utf8)
GeelabGuard.submitReceipt(withSign: signData) { [weak self] receipt, error in
if let nsError = error as NSError? {
statusMessage = "Asynchronous submission failed"
errorSummary = """
code: \(nsError.code)
message: \(nsError.localizedDescription)
"""
if [-300, -500, -501].contains(nsError.code) {
let downgrade = """
This error can be downgraded to use geeToken.
Submit it together with your business data and obtain the final environment result and fingerprint from your server.
"""
errorSummary += "\n\(downgrade)"
print(errorSummary)
}
return
}
guard let respondedGeeToken = receipt?.respondedGeeToken,
let geeToken = receipt?.geeToken else {
// TO-DO
// This error can be downgraded to use geeToken.
return
}
// TO-DO
// Send respondedGeeToken with your business data to your backend and retrieve the trusted device identification result through the Server API.
print("respondedGeeToken: \(respondedGeeToken)")
}
// Make sure the appID has been registered via `[GeelabGuard registerWithAppID:APPID];`
// Get respondedGeeToken; the result must be parsed on the server side
// This method uses an asynchronous callback
- (void)getRespondedGeeToken {
// A unique serial number or credential for this business request to prevent GeeToken from being detached from the business scenario
// If you do not need this protection, `data` can be nil
NSData *data = [@"A unique serial number or credential for this business request, used for business association and verification" dataUsingEncoding:NSUTF8StringEncoding];
// Avoid a retain cycle in the block
[GeelabGuard submitReceiptWithSignData:data completion:^(GeelabGuardReceipt * _Nullable receipt, NSError * _Nullable error) {
if (!error) {
// Send it with your business data to your backend and retrieve the trusted device identification result through the Server API.
NSLog(@"RespondedGeeToken: %@", receipt.respondedGeeToken);
}
else {
NSLog(@"error code: %ld", error.code);
NSLog(@"error: %@", error.userInfo.description);
if (error.code == -300 || error.code == -500 || error.code == -501) {
// TODO: If respondedGeeToken cannot be obtained because of a network or service response failure, you can fall back to submitting geeToken to obtain the trusted device identification result.
// Send it with your business data to your backend and retrieve the result through the Server API.
NSLog(@"geeToken: %@", receipt.geeToken);
NSLog(@"Original response: %@", receipt.originalResponse);
}
}
}];
}Error Code List
The following error codes may be returned by the asynchronous method submitReceiptWithSignData:completion::
| Error Code | Description |
|---|---|
| -200 | AppID is not registered. Please register the AppID after app launch. |
| -300 | Network error. See the details in the userInfo of the error object. |
| -500 | Invalid service response format. See receipt.originalResponse for details. |
| -501 | Service response failure. See receipt.originalResponse and provide it to technical support. |
Query GeeToken Results
Send respondedGeeToken or GeeToken with your business data to your backend. Your backend can then query the result from the Geelab Device Fingerprint service through the Server API. For details, see the Server API documentation.