1. 环境要求

2. 合规说明

2.1 隐私合规指引

集成本 SDK 时，请遵循易盾隐私合规要求：风控引擎隐私合规指引 - 网易易盾。

必须满足：请在用户同意隐私政策后，再初始化 SDK 和调用业务接口。

2.2 iOS 隐私清单要求

RiskPerception.framework 已包含 PrivacyInfo.xcprivacy。接入方仍需按 App 自身采集与使用情况，完成 App 隐私政策、App Store 隐私信息和必要权限说明。

隐私清单声明的 Required Reason API 类型包括：

隐私清单声明的采集数据类型包括：

3. 导入 SDK

3.1 添加 XCFramework

将 RiskPerception.xcframework 添加到 iOS 工程，并确认：

1. App Target 的 Frameworks, Libraries, and Embedded Content 中已包含 RiskPerception.xcframework；
2. 真机 Release 包包含 ios-arm64 产物；
3. 模拟器调试使用 ios-arm64_x86_64-simulator 产物；
4. PrivacyInfo.xcprivacy 随 framework 一起进入最终产物。

3.2 Objective-C 工程导入

在需要调用 SDK 的文件中导入：

#import <RiskPerception/HTProtect.h>
#import <RiskPerception/HTProtectConfig.h>
#import <RiskPerception/AntiCheatResult.h>

3.3 Swift 工程导入

Swift 工程直接导入模块：

import RiskPerception

如果工程使用 Objective-C Bridging Header，也可以在桥接头中导入：

#import <RiskPerception/HTProtectSwift.h>

3.4 旧接口说明

以下旧接口已废弃：

新接入文档、示例代码和 AI 辅助接入均不得再使用旧接口。

4. 初始化

前置条件（必须满足）：

• 必须在用户同意隐私政策后再调用；
• initialize / init:config:callback: 必须先于其他 SDK 接口调用；
• 建议 App 启动后完成隐私授权判断，再初始化一次；
• productId 请从易盾官网后台获取。

4.1 方法定义

Objective-C：

+ (instancetype)sharedInstance;

- (void)init:(NSString *)productId
      config:(nullable HTProtectConfig *)config
    callback:(nullable HTPCallback)callback;

Swift：

HTProtect.sharedInstance().initialize(_:config:callback:)

4.2 HTPCallback 回调说明

typedef void (^HTPCallback)(int code, NSString *msg, NSString *content);

常见 code 说明：

初始化响应内部包含 Token 缓存时长 cacheTime，默认 60 秒，具体值以服务端配置为准。SDK 根据该时长维护内存缓存；该配置不改变现有 HTPCallback 回调签名。

iOS SDK 的 RequestCmdID 包含 Cmd_GetHTPVersion 和 Cmd_GetDeviceId。iOS SDK 不提供 Cmd_SetConfigData 配置回填接口。

4.3 初始化示例

#import <RiskPerception/HTProtect.h>
#import <RiskPerception/HTProtectConfig.h>

static NSString * const kProductId = @"your_product_id";

- (void)setupRiskControl {
    // 仅在用户已同意隐私协议后初始化
    if (![self hasAgreedPrivacyPolicy]) {
        return;
    }

    HTProtectConfig *config = [[HTProtectConfig alloc] init];
    config.serverType = 1; // 1=中国大陆（默认）
    config.channel = @"AppStore";
    config.extraData = @{
        @"uid": @"123456",
        @"bizId": @"10001"
    };

    [[HTProtect sharedInstance] init:kProductId
                              config:config
                            callback:^(int code, NSString *msg, NSString *content) {
        if (code == 200) {
            // 初始化成功，可获取 Token
        } else if (code == 199) {
            // 参数错误，检查 productId / config
        } else {
            // 其他失败，记录 code / msg / content 便于排查
        }
    }];
}

import RiskPerception

func setupRiskControl() {
    // 仅在用户已同意隐私协议后初始化
    guard hasAgreedPrivacyPolicy() else {
        return
    }

    let config = HTProtectConfig()
    config.serverType = 1 // 1=中国大陆（默认）
    config.channel = "AppStore"
    config.extraData = [
        "uid": "123456",
        "bizId": "10001"
    ]

    HTProtect.sharedInstance().initialize("your_product_id", config: config) { code, msg, content in
        if code == 200 {
            // 初始化成功，可获取 Token
        } else if code == 199 {
            // 参数错误，检查 productId / config
        } else {
            // 其他失败，记录 code / msg / content 便于排查
        }
    }
}

5. HTProtectConfig 配置说明

HTProtectConfig 的配置项均为可选，按需设置。若 config 传 nil，SDK 使用默认配置。

5.1 serverType 取值

以下取值用于选择服务区域。使用中国台湾或海外服务前，请先完成对应服务区域开通。

5.2 扩展字段设置

Objective-C：

HTProtectConfig *config = [[HTProtectConfig alloc] init];
config.extraData = @{
    @"uid": @"12345",
    @"bizId": @"1"
};

Swift：

let config = HTProtectConfig()
config.extraData = [
    "uid": "12345",
    "bizId": "1"
]

5.3 私有化地址设置

host 可传完整 http/https 地址，也可传域名，SDK 会自动补全 https。

Objective-C：

config.host = @"https://your.server.com";

Swift：

config.host = "https://your.server.com"

6. 获取 Token

前置条件：必须在初始化后再调用。

同步 / 异步如何选择：

• 同步 getToken：不能在主线程调用。接口优先检查缓存 Token 是否仍在初始化响应下发的缓存时长内；缓存有效时，对缓存 Token 二次加密后立即返回，同时在后台异步刷新 Token；无缓存或缓存已过期时，立即返回降级 Token，同时触发后台异步刷新；
• 异步 getTokenAsync：每次调用都实时采集设备 / 风险数据并上报，完成后通过回调返回最新 Token，属于耗时操作。

注意事项：

• GetTokenCallback 不能为空；
• 同步接口不要在主线程调用；
• 获取到 Token 后，应随业务请求传给业务服务端，再由业务服务端调用易盾服务端校验。

初始化响应会下发 Token 缓存时长 cacheTime，默认 60 秒，具体值以服务端配置为准；缓存不会持久化到 App 本地存储。

6.1 方法定义

Objective-C：

- (AntiCheatResult *)getToken;
- (void)getTokenAsync:(GetTokenCallback)callback;

Swift：

HTProtect.sharedInstance().getToken()
HTProtect.sharedInstance().getTokenAsync(_:)

6.2 异步获取

[[HTProtect sharedInstance] getTokenAsync:^(AntiCheatResult *result) {
    if (result.code == 200 && result.token.length > 0) {
        NSString *token = result.token;
        // 每次实时采集并上报，属于耗时操作；注意兼容离线 token ~5KB
    } else {
        // 失败，参照第 7 章结果码表（result.code / result.codeStr）
    }
}];

HTProtect.sharedInstance().getTokenAsync { result in
    if result.code == 200, !result.token.isEmpty {
        let token = result.token
        // 每次实时采集并上报，属于耗时操作；注意兼容离线 token ~5KB
    } else {
        // 失败，参照第 7 章结果码表（result.code / result.codeStr）
    }
}

6.3 同步获取

dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
    AntiCheatResult *result = [[HTProtect sharedInstance] getToken];
    if (result.code == 200 && result.token.length > 0) {
        NSString *token = result.token;
        // 优先返回有效缓存的二次加密结果；同时在后台异步刷新 token
    } else {
        // 无缓存或缓存已过期时返回降级 token；同时触发后台异步刷新
    }
});

DispatchQueue.global().async {
    let result = HTProtect.sharedInstance().getToken()
    if result.code == 200, !result.token.isEmpty {
        let token = result.token
        // 上报 token
    } else {
        // 处理错误，参照第 7 章
    }
}

7. 获取 Token 的返回值（AntiCheatResult）

7.1 AntiCheatResult 类结构

@interface AntiCheatResult : NSObject

@property (nonatomic, copy) NSString *token;
@property (nonatomic, copy) NSString *businessId;
@property (nonatomic, assign) int code;
@property (nonatomic, copy) NSString *codeStr;

@end

7.2 字段说明

7.3 结果码（code）说明

7.4 token 长度与离线 token

重要：

• 业务侧不要对 token 长度做硬编码限制 / 截断，需同时兼容 40 字节的在线 token 与约 5KB 的离线 token；
• 上报字段、数据库列、网络包大小限制等都应预留足够空间，避免离线 token 被截断导致服务端校验失败；
• 离线 token 仍可正常上报，由易盾服务端识别处理，无需业务侧区分在线/离线。

8. 通用查询接口（ioctl）

8.1 方法定义

Objective-C：

- (NSString *)ioctl:(RequestCmdID)request withData:(NSString *)data;

Swift：

HTProtect.sharedInstance().ioctl(_:withData:)

8.2 参数说明

8.3 支持命令

iOS SDK 支持以上两个查询命令。不支持的查询返回空字符串。

8.4 示例代码

Objective-C：

NSString *sdkVersion = [[HTProtect sharedInstance] ioctl:Cmd_GetHTPVersion withData:@""];
NSString *deviceId = [[HTProtect sharedInstance] ioctl:Cmd_GetDeviceId withData:@""];

Swift：

let sdkVersion = HTProtect.sharedInstance().ioctl(Cmd_GetHTPVersion, withData: "")
let deviceId = HTProtect.sharedInstance().ioctl(Cmd_GetDeviceId, withData: "")

9. 接入指引

9.1 调用时序总览

sequenceDiagram
    participant App as App
    participant SDKAPI as 易盾风控SDK接口层
    participant SDKCore as 易盾风控SDK底层
    participant YD as 易盾服务端

    Note over App,SDKCore: 用户同意隐私协议后，接口调用触发 SDK 加载
    App->>SDKAPI: initialize(productId, config)
    SDKAPI->>SDKCore: 触发 SDK 加载与初始化
    SDKCore->>YD: 初始化握手 / 拉取在线配置
    YD-->>SDKCore: 初始化响应（业务配置、Token 缓存时长，默认 60 秒）
    SDKCore->>SDKCore: 保存业务配置并记录 Token 缓存时长
    SDKCore-->>SDKAPI: SDK 加载完成
    Note over SDKAPI,SDKCore: 后续 Token 接口复用已加载组件
    SDKAPI-->>App: HTPCallback(code, msg, content)

    Note over App,SDKCore: 业务接口调用触发 Token 获取
    App->>SDKAPI: getToken（同步，放在子线程）
    SDKAPI->>SDKCore: 触发同步 Token 获取
    SDKCore->>SDKCore: 检查缓存 Token 是否超过缓存时长
    alt 缓存有效
        SDKCore->>SDKCore: 对缓存 Token 二次加密
        SDKCore-->>SDKAPI: AntiCheatResult(缓存 Token)
        SDKAPI-->>App: 立即返回缓存 Token
    else 无缓存或缓存已过期
        SDKCore->>SDKCore: 生成降级 Token
        SDKCore-->>SDKAPI: AntiCheatResult(降级 Token)
        SDKAPI-->>App: 立即返回降级 Token
    end

    Note over SDKAPI,SDKCore: 同步 getToken 返回后，底层同时执行后台异步刷新
    SDKCore->>SDKCore: 实时采集设备 / 风险数据
    SDKCore->>YD: 上报采集数据并请求新 Token
    YD-->>SDKCore: 返回新 Token
    SDKCore->>SDKCore: 按 Token 缓存时长更新内存缓存

    App->>SDKAPI: getTokenAsync(callback)（异步，耗时）
    SDKAPI->>SDKCore: 触发实时 Token 获取
    SDKCore->>SDKCore: 每次实时采集设备 / 风险数据
    SDKCore->>YD: 上报采集数据并请求最新 Token
    YD-->>SDKCore: 返回最新 Token
    SDKCore->>SDKCore: 按 Token 缓存时长更新内存缓存
    SDKCore-->>SDKAPI: AntiCheatResult(最新 Token)
    SDKAPI-->>App: callback(最新 Token)

时序图中的 Token 缓存时长由初始化响应下发，默认 60 秒；仅当缓存 Token 未超过该时长时，getToken 才会走缓存二次加密分支。

9.2 推荐接入流程

1. 向运营获取 productId（必传）；
2. 在隐私政策弹窗中加入易盾智能风控 SDK 采集授权说明；
3. 用户同意隐私协议后，构建 HTProtectConfig 并调用初始化接口；
4. 初始化回调 code==200 后，在业务节点通过 getTokenAsync 实时采集并上报 Token（耗时操作）；
5. 对时延敏感的业务可在子线程使用 getToken 获取 Token：缓存有效时二次加密后立即返回，缓存无效时返回降级 Token，并同时触发后台刷新；
6. 客户端将 Token 随业务请求完整上报至业务服务端；服务端后续处理不属于客户端接入范围。

9.3 接入建议

• 必须在用户同意隐私政策后再初始化；
• 初始化接口必须先于所有其他接口调用；
• getToken 不要在主线程调用；
• GetTokenCallback 不要传 nil；
• HTProtectConfig 尽量在初始化前配置完整；
• 客户端职责止于获取并上报 Token，不在客户端执行风控校验或决策。

9.4 排查信息收集清单

排查接入问题时，建议先收集以下信息：

10. 如何验证接入成功

按以下清单逐步自检，全部通过即视为接入成功。

10.1 编译与打包验证

10.2 初始化验证

• 初始化回调返回 code == 200；
• 若返回 199：检查 productId / config 入参；
• 若返回其他失败：记录 code、msg、content 后进入异常排查流程。

Objective-C：

[[HTProtect sharedInstance] init:@"your_product_id" config:config callback:^(int code, NSString *msg, NSString *content) {
    NSLog(@"HTProtect init code=%d, msg=%@, content=%@", code, msg, content);
    // 期望看到 code=200
}];

Swift：

HTProtect.sharedInstance().initialize("your_product_id", config: config) { code, msg, content in
    print("HTProtect init code=\(code), msg=\(msg), content=\(content)")
    // 期望看到 code=200
}

10.3 获取 Token 验证

• 调用 getTokenAsync，回调返回 result.code == 200 且 result.token 非空；
• 打印长度确认：正常网络下约 40 字节；断网/弱网下可能为 离线 token（~5KB），二者均属正常。

Objective-C：

[[HTProtect sharedInstance] getTokenAsync:^(AntiCheatResult *result) {
    NSLog(@"code=%d, codeStr=%@, len=%lu",
          result.code,
          result.codeStr,
          (unsigned long)result.token.length);
}];

Swift：

HTProtect.sharedInstance().getTokenAsync { result in
    print("code=\(result.code), codeStr=\(result.codeStr), len=\(result.token.count)")
}

10.4 通用查询验证

调用 ioctl 查询 SDK 版本和服务端设备指纹：

Objective-C：

NSString *sdkVersion = [[HTProtect sharedInstance] ioctl:Cmd_GetHTPVersion withData:@""];
NSString *deviceId = [[HTProtect sharedInstance] ioctl:Cmd_GetDeviceId withData:@""];

Swift：

let sdkVersion = HTProtect.sharedInstance().ioctl(Cmd_GetHTPVersion, withData: "")
let deviceId = HTProtect.sharedInstance().ioctl(Cmd_GetDeviceId, withData: "")

10.5 Token 上报验证

• 客户端能将 token 随业务请求完整上报至业务服务端；
• 业务服务端能正常接收 token，且在线 / 离线 token 均未被截断；
• 服务端后续风控处理不属于客户端接入范围。

10.6 接入成功判定

同时满足以下条件，即接入成功：

1. init 回调 code == 200；
2. getToken 回调 code == 200 且 token 非空；
3. 在线/离线 token 均能完整上报、不被截断；
4. 业务服务端能完整接收客户端上报的 token。

11. FAQ / 异常排查

11.1 初始化相关

Q：调用初始化后没有任何回调 / 回调 code 非 200？

排查顺序：

• 确认 productId 是否正确；
• 确认 host（如配置）是否可达；
• 确认 callback 未传 nil，否则无法接收初始化结果；
• 确认是否在用户同意隐私协议之后调用。

Q：可以重复调用初始化接口吗？

不建议，请保证初始化只执行一次。若确需切换服务区域或配置，请在初始化前完成服务区域与配置规划。

11.2 获取 Token 相关

Q：如何选择同步还是异步调用？

• 同步 getToken：缓存 Token 在缓存时长内时二次加密后立即返回；无缓存或缓存已过期时返回降级 Token，并同时触发后台异步刷新。必须放子线程；
• 异步 getTokenAsync：每次实时采集数据并上报，完成后通过回调返回最新 Token，属于耗时操作。

Q：getTokenAsync 回调返回 code == 201（error not init）？

说明 SDK 尚未初始化或初始化未完成：

• 确认初始化接口已先于 getTokenAsync 调用；
• 建议在初始化成功（code==200）后再触发首次取 Token。

Q：同步 getToken 返回 code == 202？

说明同步接口在主线程调用。请放到后台线程执行。

11.3 工程集成相关

Q：编译时报找不到 RiskPerception 或 HTProtect？

• 确认 RiskPerception.xcframework 已添加到 App Target；
• 确认 Swift 工程已 import RiskPerception；
• Objective-C 工程确认已导入对应 SDK 头文件；
• 如使用桥接头，确认 Bridging Header 路径配置正确。

Q：为什么不使用 NTESRiskUniPerception？

旧主接口已废弃。新接入请统一使用 HTProtect。

11.4 误封 / 误判相关

Q：SDK 会不会直接封禁用户？

不会。SDK 侧不做封禁决策，最终是否拦截、如何处置，由业务服务端结合易盾返回的风险标签自行决定。

Q：token 校验失败（code != 200）是否等于用户有问题？

不是。code != 200 多数是环境 / 网络 / 时序问题，并非用户作弊。请先按 7.3 结果码表排查技术原因，不要直接对用户做处置。

11.5 性能 / 稳定性影响相关

Q：接入后会不会拖慢 App 启动 / 卡顿？

• 初始化会保存产品上下文、应用配置、拉取在线配置，并在初始化成功后触发一次后台 Token 预取；
• 同步 getToken 优先返回缓存或降级 Token，并在后台异步刷新；
• 异步 getTokenAsync 每次实时采集并上报，属于耗时操作，回调在完成后触发；
• 同步 getToken 不能在主线程调用。

Q：取 token 可以高频调用吗？

不建议。请在关键业务节点按需获取，不要在循环或高频回调中反复调用。

11.6 数据获取与处理相关

Q：SDK 会主动申请系统权限吗？

不会。SDK 自身不主动弹窗申请系统权限。如业务 App 自身需要申请权限，请按业务合规要求完成告知与授权。

Q：必须在用户同意隐私政策后才能初始化吗？

是，这是强制要求。必须在用户同意隐私政策后再初始化 SDK，并在隐私政策弹窗中加入本 SDK 的采集授权说明。

Q：海外 / GDPR 场景需要注意什么？

可通过海外数据中心确保数据在合规区域处理。接入海外服务前，请完成对应服务区域开通。

12. AI 辅助接入 Prompt 约束

你是「易盾智能风控 SDK-iOS」接入助手。请严格依据本接入文档回答与生成代码，遵守以下约束：

【API 白名单（仅可使用以下新接口）】
- [HTProtect sharedInstance]
- [[HTProtect sharedInstance] init:productId config:config callback:callback]
- HTProtect.sharedInstance().initialize(_:config:callback:)
- [[HTProtect sharedInstance] getToken] / HTProtect.sharedInstance().getToken()
- [[HTProtect sharedInstance] getTokenAsync:callback] / HTProtect.sharedInstance().getTokenAsync(_:)
- [[HTProtect sharedInstance] ioctl:request withData:data] / HTProtect.sharedInstance().ioctl(_:withData:)
- HTProtectConfig 属性：serverType / host / channel / extraData
- AntiCheatResult 字段：token / businessId / code / codeStr
- RequestCmdID：Cmd_GetHTPVersion / Cmd_GetDeviceId

不得调用旧接口 NTESRiskUniPerception / NTESRiskUniConfiguration；
不得编造 Cmd_SetConfigData 或其他未公开 RequestCmdID；
如涉及未列出的能力，请明确回复「文档未提供该 API」。

【关键事实（不得偏离）】
- 成功码统一为 code == 200；其余 code（201/202/203/204）均为失败。
- 结果对象为 AntiCheatResult，判断成功用 result.code == 200，禁止使用 ret 等旧写法。
- 初始化响应包含 Token 缓存时长：cacheTime 默认 60 秒，具体值以服务端配置为准；不会持久化到 App 本地存储。
- 同步 getToken：不能在主线程调用；缓存 Token 在缓存时长内时二次加密后立即返回，无缓存或缓存已过期时返回降级 Token，并同时触发后台异步刷新。
- 异步 getTokenAsync：每次实时采集数据并上报，属于耗时操作，完成后回调返回最新 Token。
- init 必须满足：用户已同意隐私政策、先于其他接口调用；回调 code==200 后方可取 token。
- token 长度：在线约 40 字节，离线约 5KB；禁止对 token 做长度限制或截断。
- HTProtectConfig 除 init 的 productId 外全部可选；host 仅私有化、测试环境或指定服务域名需要。
- iOS SDK 的 ioctl 仅支持 Cmd_GetHTPVersion / Cmd_GetDeviceId。
- SDK 不做封禁决策、不主动申请系统权限。

【输出要求】
- 生成代码须区分 Objective-C 与 Swift；同步取 token 的示例必须放在子线程。
- 涉及合规/采集字段问题时，按隐私合规指引(2.1)与 iOS 隐私清单要求(2.2)回答，不臆造采集字段。
- API 白名单未列出的能力，明确回复「文档未提供该 API」，不做猜测性回答。