iOS 集成指南
iOS SDK 的安装、注册、Token 获取与隐私清单要求
概述与资源
GeelabGuard iOS SDK 面向集成 iOS 原生客户端的开发者提供。该 SDK 不依赖任何第三方库。
环境要求
| 项目 | 资源 |
|---|---|
| 目标平台 | 兼容 iOS 9+ |
| 开发环境 | Xcode 13.0+ |
| 系统依赖 | 无 |
| SDK 第三方依赖 | 无 |
安装
获取 SDK
请登录控制台下载。
导入 SDK
-
如果手动添加 SDK,请将下载的
GeelabGuardSDK.xcframework文件拖入项目,并确保勾选Copy items if needed。请通过
Linked Frameworks and Libraries导入 xcframework。将GeelabGuardSDK.xcframework拖入项目后,还需确认.xcframework已添加到PROJECT -> Build Phases -> Linked Frameworks and Libraries下。 -
对于静态库中的
Category符号,请在对应 target 的Build Settings->Other Linker Flags中添加-ObjC。 -
设备验证 iOS SDK 会使用部分 API 获取磁盘容量和环境检测信息,用于风控目的。这涉及
NSPrivacyAccessedAPICategoryDiskSpace和NSPrivacyAccessedAPICategoryFileTimestamp类别。
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必须与管理后台中的区域设置相对应。
| 区域 | submitServerUrl |
|---|---|
| 🌏 全球 | https://riskct-global.geelabapi.com/api/v1/client_report |
| 🇪🇺 欧洲 | https://riskct-eu.geelabapi.com/api/v1/client_report |
| 🇺🇸 北美 | https://riskct-na.geelabapi.com/api/v1/client_report |
// 默认服务节点
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: 可能返回以下错误码:
| 错误码 | 说明 |
|---|---|
| -200 | AppID 未注册。请在应用启动后注册 AppID。 |
| -300 | 网络错误。请查看 error 对象 userInfo 中的详细信息。 |
| -500 | 服务响应格式无效。请查看 receipt.originalResponse 获取详情。 |
| -501 | 服务响应失败。请查看 receipt.originalResponse,并提供给技术支持。 |
查询 GeeToken 结果
将 respondedGeeToken 或 GeeToken 与业务数据一同提交到您的业务服务端。服务端随后向 Geelab 设备指纹服务查询结果。详情请参见 服务端文档。