设备指纹
接入指南

iOS 集成指南

iOS SDK 的安装、注册、Token 获取与隐私清单要求

概览与资源

GeelabGuard iOS SDK 面向需要在 iOS 原生客户端中集成的开发者。该 SDK 不依赖任何第三方库。

环境要求

项目资源
目标平台兼容 iOS 9+
开发环境Xcode 13.0+
系统依赖
SDK 第三方依赖

安装

获取 SDK

请登录控制台下载 SDK。

导入 SDK

  1. 如需手动添加 SDK,请将下载的 GeelabGuardSDK.xcframework 文件拖入项目,并确认已勾选 Copy items if needed

    请通过 Linked Frameworks and Libraries 导入 xcframework。将 GeelabGuardSDK.xcframework 拖入项目后,还需要确认 .xcframework 已添加到 PROJECT -> Build Phases -> Linked Frameworks and Libraries

  2. 对于静态库中的 Category 符号,请在对应 target 的 Build Settings -> Other Linker Flags 中添加 -ObjC

  3. 设备验证 iOS SDK 会使用部分 API 获取磁盘容量和环境检测信息,用于风控目的。这涉及 NSPrivacyAccessedAPICategoryDiskSpaceNSPrivacyAccessedAPICategoryFileTimestamp 类别。

Apple 在 WWDC23 公布了面向应用和 SDK 的新隐私政策。可参考 Get started with privacy manifests - WWDC23 - Videos - Apple Developer。Apple 也在 7 月 27 日发布了相关新闻更新:自 2023 年秋季起,如果新上传的应用使用相关 API 但未提供隐私清单,您将收到邮件提醒;自 2024 年春季起,隐私清单将成为强制要求。涉及的 API 及可接受的使用原因可参考 Describing use of required reason API | Apple Developer Documentation。如果您的使用原因不在列表中,也可以直接提交具体说明。

创建新隐私清单的说明请参考 Privacy manifest files | Apple Developer Documentation

代码示例

导入头文件

将验证动态框架 GeelabGuardSDK.framework 的头文件导入项目。

#import <GeelabGuardSDK/GeelabGuardSDK.h>

应用启动后立即注册 appID 并配置服务区域

在管理后台创建 ID 时,serverURL 必须与所选区域配置一致。

// 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;
}

获取 respondedGeeToken

使用 GeelabGuardSDK 对数据进行签名,并获取环境检测 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);
            }
        }
    }];
}

错误码列表

异步方法 submitReceiptWithSignData:completion: 可能返回以下错误码:

错误码说明
-200AppID 未注册。请在应用启动后注册 AppID。
-300网络错误。详情请查看错误对象的 userInfo
-500服务响应格式无效。详情请查看 receipt.originalResponse
-501服务响应失败。请查看 receipt.originalResponse 并提供给技术支持。

查询 GeeToken 结果

respondedGeeTokenGeeToken 与业务数据一起提交到业务服务器。服务器随后向 Geelab 设备指纹服务查询结果。详情请参考 服务端文档