iOS 集成指南
iOS SDK 的安装、注册、Token 获取与隐私清单要求
概览与资源
GeelabGuard iOS SDK 面向需要在 iOS 原生客户端中集成的开发者。该 SDK 不依赖任何第三方库。
环境要求
| 项目 | 资源 |
|---|---|
| 目标平台 | 兼容 iOS 9+ |
| 开发环境 | Xcode 13.0+ |
| 系统依赖 | 无 |
| SDK 第三方依赖 | 无 |
安装
获取 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 时,
serverURL必须与所选区域配置一致。
| 区域 | serverURL |
|---|---|
| 🌏 全球(默认) | 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 |
// 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: 可能返回以下错误码:
| 错误码 | 说明 |
|---|---|
| -200 | AppID 未注册。请在应用启动后注册 AppID。 |
| -300 | 网络错误。详情请查看错误对象的 userInfo。 |
| -500 | 服务响应格式无效。详情请查看 receipt.originalResponse。 |
| -501 | 服务响应失败。请查看 receipt.originalResponse 并提供给技术支持。 |
查询 GeeToken 结果
将 respondedGeeToken 或 GeeToken 与业务数据一起提交到业务服务器。服务器随后向 Geelab 设备指纹服务查询结果。详情请参考 服务端文档。