设备指纹
接入指南

iOS 集成指南

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

概述与资源

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

环境要求

项目资源
目标平台兼容 iOS 9+
开发环境Xcode 13.0+
系统依赖
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 时,SubmitServerUrl 必须与管理后台中的区域设置相对应。

// 默认服务节点
GeelabGuard.register(withAppID: appID)
// 指定服务节点
// GeelabGuard.register(withAppID: appID, serverURL: serverURL)
// 使用您控制台账号生成的 APPID
#define APPID @"abcdef123456********ef1234567890"
// 如有需要,可指定服务 URL
// 全球服务,SDK 已预配置
#define SubmitServerURL @"https://riskct-global.geelabapi.com/api/v1/client_report"
// 欧洲
// #define SubmitServerURL @"https://riskct-eu.geelabapi.com/api/v1/client_report"
// 北美
// #define SubmitServerURL @"https://riskct-na.geelabapi.com/api/v1/client_report"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 注册您的 AppID,使用全球服务
    [GeelabGuard registerWithAppID:APPID];
    // 使用其他区域的服务
    // [GeelabGuard registerWithAppID:APPID serverURL:SubmitServerURL];

    return YES;
}

获取 respondedGeeToken

使用 GeelabGuardSDK 对数据进行签名,并获取环境检测 GeeToken:

// 可选,可以为 nil
let signData = "本次业务请求的唯一序列号或凭证,用于业务关联和校验".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
        // 此错误可降级使用 geeToken。
        print("geeToken: \(receipt?.geeToken)")
        return
    } 

    // TO-DO
    // 将 respondedGeeToken 与业务数据一同提交,并从您的服务端获取最终环境结果和指纹。
    print("respondedGeeToken: \(respondedGeeToken)")

}

// 确保 appID 已通过 `[GeelabGuard registerWithAppID:APPID];` 注册
// 获取 respondedGeeToken;结果必须在服务端解析
// 此方法使用异步回调
- (void)getRespondedGeeToken {

    // 本次业务请求的唯一序列号或凭证,用于防止 GeeToken 脱离业务场景
    // 如果不需要此保护,`data` 可以为 nil
    NSData *data = [@"本次业务请求的唯一序列号或凭证,用于业务关联和校验" dataUsingEncoding:NSUTF8StringEncoding];

    // 避免 block 中的循环引用
    [GeelabGuard submitReceiptWithSignData:data completion:^(GeelabGuardReceipt * _Nullable receipt, NSError * _Nullable error) {
        if (!error) {
            // 与业务数据一同提交,并在服务端获取最终环境识别结果和指纹
            // API 参数请参考服务端文档:https://docs.geelab.tech/zh/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: 如果因网络或服务响应失败无法获取 respondedGeeToken,可以降级使用 geeToken
                // 与业务数据一同提交,并在服务端获取最终环境识别结果和指纹
                // API 参数请参考服务端文档:https://docs.geelab.tech/zh/docs/device-fingerprint/deployment/server
                NSLog(@"geeToken: %@", receipt.geeToken);
                NSLog(@"Original response: %@", receipt.originalResponse);
            }
        }
    }];
}

错误码列表

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

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

查询 GeeToken 结果

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