Device Fingerprint
Deployment

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

ItemResource
Target PlatformCompatible with iOS 9+
Development EnvironmentXcode 13.0+
System DependenciesNone
SDK Third-Party DependenciesNone

Installation

Obtain the SDK

Please log in to the console to download it.

Import the SDK

  1. If you add the SDK manually, drag the downloaded GeelabGuardSDK.xcframework file into your project and make sure Copy items if needed is checked.

    Please import the xcframework via Linked Frameworks and Libraries. After dragging GeelabGuardSDK.xcframework into the project, also verify that the .xcframework has been added under PROJECT -> Build Phases -> Linked Frameworks and Libraries.

  2. For Category symbols inside the static library, add -ObjC to Build Settings -> Other Linker Flags for the corresponding target.

  3. 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 NSPrivacyAccessedAPICategoryDiskSpace and NSPrivacyAccessedAPICategoryFileTimestamp categories.

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

serverURL must be corresponding to your region settings when creating ID in the admin panel.

// 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 CodeDescription
-200AppID is not registered. Please register the AppID after app launch.
-300Network error. See the details in the userInfo of the error object.
-500Invalid service response format. See receipt.originalResponse for details.
-501Service 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.