iOS Integration
Installation, registration, token retrieval, and privacy manifest notes for the iOS SDK
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.Please import the xcframework via
Linked Frameworks and Libraries. After draggingGeelabGuardSDK.xcframeworkinto the project, also 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 device verification iOS SDK uses some of these APIs to obtain disk capacity and environment inspection information for risk control purposes. 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 be corresponding to your region settings when creating ID in the admin panel.
| Region | serverURL |
|---|---|
| 🌏 Global(Default) | https://riskct-global.geelabapi.com/api/v1/client_report |
| 🇪🇺 Europe | https://riskct-eu.geelabapi.com/api/v1/client_report |
| 🇺🇸 North America | https://riskct-na.geelabapi.com/api/v1/client_report |
// default service node
GeelabGuard.register(withAppID: appID)
// specified service node
// GeelabGuard.register(withAppID: appID, serverURL: serverURL)// Use the APPID 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/v1/client_report"
// Europe
// #define SubmitServerURL @"https://riskct-eu.geelabapi.com/api/v1/client_report"
// North America
// #define SubmitServerURL @"https://riskct-na.geelabapi.com/api/v1/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 an environment-detection 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
guard let nsError = error as NSError?,
let respondedGeeToken = receipt?.respondedGeeToken else {
// TO-DO
// Please downgraded if errors occured.
print("geeToken: \(receipt?.geeToken)")
return
}
// TO-DO
// Submit respondedGeeToken together with your business data and obtain the final environment result and fingerprint from your server.
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) {
// Submit it together with your business data and retrieve the final environment recognition result and fingerprint on the server side
// For API parameters, refer to the server documentation: https://docs.geelab.tech/en/docs/device-fingerprint/deployment/server
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 network or service response failure, you can fall back to your custom method
// Submit it together with your business data and retrieve the final environment recognition result and fingerprint on the server side
// For API parameters, refer to the server documentation: https://docs.geelab.tech/en/docs/device-fingerprint/deployment/server
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
Submit respondedGeeToken or GeeToken together with your business data to your business server. The server then queries the result from the Geelab device fingerprint service. For details, see the server documentation.