智能风控 iOS 端接入文档（OC）
隐私说明
请参照网易易盾隐私政策，请将易盾隐私政策链接放到应用“用户协议”中。
接入说明
接入“智能风控” SDK，开发者需要完成以下步骤：
1. 根据应用/游戏开发平台，将SDK拷贝到指定的工程目录，并修改项目配置；
2. 接入风控SDK必接接口，根据业务需求接入建议接口；
3. 测试风控SDK接入是否正确；
4. 验证风控SDK功能效果；
5. 按业务常规发版流程进行测试与发版；
应用必须接入：
游戏必须接入：
建议接入：
接入步骤
请登陆易盾官网后台风控引擎-服务管理获取sdk，详情如图。
SDK 涉及到以下文件：
SDK 涉及到以下文件：
注意：本SDK最低支持的系统：iOS 9.0
RiskPerception.framework
导入SDK
（1）将RiskPerception.framework文件拷贝到iOS项目工程目录下（可放在任意子目录）。
（2）在“Build Phases”->“Link Binary With Libraries”内添加对RiskPerception.framework的引用。
（3）在“Build Phases”->“Link Binary With Libraries”内添加AvFoundation.framework、CoreTelephony.framework、SystemConfiguration.framework、libc++.tbd的引用
此时需要保证“General”->“Frameworks, Libraries, and Embedded Content”中相关库和框架的集成方式为Do Not Embed
（4）在“Building Setting”->“Other Linker Flags”中添加 -ObjC、-fprofile-instr-generate、-lz
（5）在“Building Setting”->“Enable Bitcode”中关闭bitcode
部分产品相关参数请用账号登陆易盾官网控制台获取参考
SDK 接入调用说明
SDK 初始化接口（init）
接口用途：
用于初始化智能风控 SDK。
接入须知：
-
使用其他接口之前，必须先调用初始化接口，建议在应用/游戏启动过后第一时间调用（初始化后，并不会获取任何个人隐私相关信息）；
-
该接口为 必须调用接口。
函数原型：
- (void)init:(NSString *)productId callback:(HTPCallback __nullable)callback;
参数说明：
| 参数 | 说明 | 必要性 |
|---|---|---|
| productId | 易盾HTP分配的productId，可登录易盾后台获取 | 必填 |
| callback | 初始化是否成功的回调函数 | 可选，不需要可填nil |
配置类NTESRiskUniConfiguration设置：
(1) 设置服务器归属地
+ (void)setServerType:(NSInteger)type;
智能风控默认上报的服务器为中国大陆的服务器，若需要更改服务器归属地，可以调用该接口进行配置，支持的类型如下：
| 参数 | 赋值 | 说明 |
|---|---|---|
| serverType | 1 | 中国大陆地区，默认为该值，无需设置 |
| serverType | 2 | 中国台湾地区 |
| serverType | 3 | 海外地区 |
| serverType | 5 | 支持IPv6 |
(2) 设置渠道信息
+ (void)setChannel:(NSString *)channel;
若需要传递当前应用包体来源渠道可调用该接口（比如：App Store CN/App Store EU）。
(3) 设置额外数据
+ (void)setExtraData:(NSString *)key forValue:(NSString *)value;
若需要客户端传递额外信息给易盾，可调用该接口，支持多次调用，但必须在 init 之前设置。
(4) 设置私有化地址
+ (void)setHost:(NSString *)host;
私有化的客户需要通过该接口设置服务器地址，其他客户可以忽略。
参数说明
- 配置域名的，只需填写域名即可，SDK会自动加上前缀“https://”，举例如下所示：
[NTESRiskUniConfiguration setHost:@"xxxxx.xxxx.xxxx"];
- 配置ip和端口的，举例如下所示：
[NTESRiskUniConfiguration setHost:@"xx.xx.xx.xx:xxx"];
回调接口：
callback:^(int code, NSString * _Nonnull msg, NSString * _Nonnull content) {
// 如果code == 200，说明初始化成功
// 如果code == 199，说明初始化参数错误，如productId不合法或者过期
// 如果code == 400，请将 content 发送到贵方服务端，由贵方服务端通过[getConfig接口[配置下发接口](https://support.dun.163.com/documents/761315885761396736?docId=771983453572567040)](https://support.dun.163.com/documents/761315885761396736?docId=771983453572567040)转发给易盾服务端，由易盾服务端响应
// 易盾服务端返回结果，再将结果通过 通用查询接口(Cmd_SetConfigData) 反馈给反外挂sdk
// configData为易盾服务端返回的数据
[[NTESRiskUniPerception fomentBevelDeadengo] ioctl:Cmd_SetConfigData withData: configData];
}
如需要示例 demo 请联系易盾获取。
示例代码：
// 设置数据上报的服务器归属地，应用/游戏根据自身发行地区来控制
[NTESRiskUniConfiguration setServerType:2];
// 设置渠道信息
[NTESRiskUniConfiguration setChannel:@"App Store"];
// 设置额外数据
[NTESRiskUniConfiguration setExtraData:@"GameVersion" forValue:@"1.0.0"];
[NTESRiskUniConfiguration setExtraData:@"AssetVersion" forValue:@"1.0.0"];
// 设置请求域名
[NTESRiskUniConfiguration setHost:@"ir-sdk.netease.com"];
//调用sdk初始化接口
[[NTESRiskUniPerception fomentBevelDeadengo] init:@"易盾提供的产品id" callback:^(int code, NSString * _Nonnull msg, NSString * _Nonnull content) {
// code返回200说明初始化成功
}];
设置用户信息接口（setRoleInfo）
接口用途：
游戏类型应用，在进行数据采集的过程中，会将角色 ID，角色名称、用户/角色账号等设置在风控 SDK 采集的数据中一同上传，用于表示角色信息，以便对有恶意、风险行为的用户/角色进行相应的处置。
接口须知：
-
须在 SDK 初始化且 用户同意隐私政策后才能调用该接口；
-
凡事涉及到用户登录、或者切换角色的地方，均需要调用该接口设置或者更新用户/玩家信息；
函数原型：
- (int)setRoleInfo:(NSString *)businessId
roleId:(NSString *)roleId
roleName:(NSString *)roleName
roleAccount:(NSString *)roleAccount
roleServer:(NSString *)roleServer
serverId:(int)serverId
gameJson:(NSString *)gameJson;
参数说明：
| 参数 | 说明 | 必要性 |
|---|---|---|
| businessId | 当前业务 ID | 必填 |
| roleId | 用户/玩家的角色 ID；非游戏类型应用，roleId 可以与 roleAccount 相同 | 必填 |
| roleName | 用户/玩家的角色名称；非游戏类型应用，roleName 可以是当前用户昵称相同 | 可选，不需要可填空 |
| roleAccount | 用户/玩家的账号；如业务方同时接入易盾反垃圾，则此账号需要与反垃圾接入中的account一致 | 可选，不需要可填空 |
| roleServer | 用户/玩家的角色的服务器名称 | 可选，不需要可填空 |
| serverId | 用户/玩家的角色所属服务器的 ID | 可选，不需要可填-1 |
| gameJson | 游戏类型应用需要上传的信息，对应一个 json 字符串 | 可选，不需要可填空 |
gameJson 字段说明：
| key 名称 | key 类型 | key 值 | 必要性 | 说明 |
|---|---|---|---|---|
| 游戏版本号 | String | GameVersion | 可选，不需要可填null | 游戏版本号 |
| 资源文件版本 | String | AssetVersion | 可选，不需要可填null | 游戏类型应用的资源文件版本号 |
返回值：
| 值 | 说明 |
|---|---|
| 0 | 成功 |
| 201 | 未初始化 |
| 203 | 参数不合法 |
示例代码：
NSDictionary *object = @{
@"GameVersion" : @"1.0.1",
@"AssetVersion" : @"1.0.1"
};
NSData *jsonData = [NSJSONSerialization dataWithJSONObject:object options:NSJSONWritingPrettyPrinted error:nil];
NSString *jsonString = [[NSString alloc]initWithData:jsonData encoding:NSUTF8StringEncoding];
int ret = [[NTESRiskUniPerception fomentBevelDeadengo] setRoleInfo:@"易盾提供的业务id"
roleId:@"123456"
roleName:@"易小盾"
roleAccount:@"yd@163.com"
roleServer:@"游戏测试服"
serverId:1
gameJson:jsonString];
登出接口（logOut）
接口用途：
为了更好的统计该用户/玩家角色在本次登录后的行为，精准标识和打击有恶意行为的用户/玩家。
接入须知：
-
须在 设置用户信息接口被调用后方可调用，在用户/玩家退出当前角色（包括切换角色）或者退出游戏时调用接口。
-
此接口主要用于判断用户/玩家本次生命周期，不强制要求接入。
-
如果未调用初始化，此接口默认为空，不会执行任何逻辑。
函数原型：
- (void)logOut;
示例代码：
[[NTESRiskUniPerception fomentBevelDeadengo] logOut];
同步获取凭证（getToken）
接口用途：
用于关键业务节点风险防控场景中，比如注册、登录、领劵、抽卡、兑换、点赞、评论等业务场景。业务方可通过此接口，获取检测唯一凭证 token。业务服务端通过此凭证实时获取当前用户/玩家风险检测结果，并根据结果进行处置。
接口适用场景为:
1、游戏类应用，当 SDK 数据上报接口被屏蔽导致数据上报失败时，通过 getToken 接口获取 SDK 采集信息，并由客户服务端传递给易盾服务器；
2、全类型应用，在关键业务节点主动调用检测时，通过 getToken 接口获取检测凭证，由客户服务端通过 token 凭证从易盾服务器查询检测结果。
接入须知：
-
内部存在网络请求，只允许在子线程上调用。
-
返回值AntiCheatResult中token的使用方法请参考“后端接入-智能风控数据服务接口-在线检测接口”。
函数原型：
- (AntiCheatResult *)getToken:(NSString *)businessId withTimeout:(int)timeout;
参数说明：
| 参数 | 说明 | 必要性 |
|---|---|---|
| businessId | 业务 ID | 必填，由易盾后台分配，并在官网“服务管理”中查询 |
| timeout | 函数超时时间 | 必填，单位毫秒，[1000,10000]，此区间外的默认为300 |
返回值：
AntiCheatResult类说明：
@interface AntiCheatResult : NSObject
@property (nonatomic, copy) NSString *token;
@property (nonatomic, copy) NSString *businessId;
@property (nonatomic, assign) int code;
@property (nonatomic, assign) NSString *codeStr;
@end
AntiCheatResult变量说明：
| 变量 | 说明 |
|---|---|
| code | 结果码，不同结果码含义如下：200：表示调用成功，其他结果码均表示调用失败；201：SDK未初始化；202：在主线程运行；203：businessId不合法；204：其他情况 |
| codeStr | 结果码对应的字符说明，200：success；201：error. not init；202：error. run on main thread；203：businessId invalid；204：gen token error |
| token | 当 code 为200时，返回正常token。当网络状态不佳或者超时时，会返回离线 token |
| businessId | 由易盾后台分配，并在官网“服务管理”中查询 |
示例代码：
AntiCheatResult *result = [[NTESRiskUniPerception fomentBevelDeadengo] getToken:@"易盾提供的业务id" withTimeout:2000];
if (tolen.code == 200) {
// 调用成功，获取token
NSLog(@"sync token:%@",result);
}
异步获取凭证（getTokenAsync）
接口用途：
同 同步获取凭证。
接入须知：
-
在主线程调用，回调也在主线程。
-
返回值AntiCheatResult中token的使用方法请参考“后端接入-智能风控数据服务接口-在线检测接口”。
函数原型：
- (void)getTokenAsync:(NSString *)businessId
withTimeout:(int)timeout
completeHandler:(GetTokenCallback)callback;
参数说明：
| 参数 | 说明 | 必要性 |
|---|---|---|
| businessId | 业务 ID | 必填，由易盾后台分配，并在官网“服务管理”中查询 |
| timeout | 函数超时时间 | 必填，单位毫秒，[1000,10000]，此区间外的默认为3000 |
| callback | token 的回调 | 必填，用来接收 token |
GetTokenCallback说明：
typedef void (^GetTokenCallback)(AntiCheatResult *result);
AntiCheatResult类说明：
@interface AntiCheatResult : NSObject
@property (nonatomic, copy) NSString *token;
@property (nonatomic, copy) NSString *businessId;
@property (nonatomic, assign) int code;
@property (nonatomic, assign) NSString *codeStr;
@end
AntiCheatResult变量说明：
| 变量 | 说明 |
|---|---|
| code | 结果码，不同结果码含义如下：200：表示调用成功，其他结果码均表示调用失败；201：SDK未初始化；202：在主线程运行；203：businessId不合法；204：其他情况 |
| codeStr | 结果码对应的字符说明，200：success；201：error. not init；202：error. run on main thread；203：businessId invalid；204：gen token error |
| token | 当 code 为200时，返回正常token。当网络状态不佳或者超时时，会返回离线 token |
| businessId | 由易盾后台分配，并在官网“服务管理”中查询 |
示例代码：
注意： 特别的，当需要在回调中进行某些操作时，需要注意该操作是否是线程安全的，如在cocos-lua项目中，由于lua并不支持多线程，请将lua的方法调用放在主线程进行
[[NTESRiskUniPerception fomentBevelDeadengo] getTokenAsync:@"易盾提供的业务id" withTimeout:3000 completeHandler:^(AntiCheatResult * _Nonnull result) {
NSLog(@"async token :%@", result.token);
dispatch_async(dispatch_get_main_queue(), ^{
//do something...
});
}];
交互接口（ioctl）
接口用途：
用于在客户端查询 SDK 采集的基础数据、设置需要传递给 SDK 数据（比如初始化配置内容、check 结果信息等）、及其他可能的定制功能服务。
接入须知：
接口调用前置条件是：调用了初始化接口以及同意隐私政策之后。
函数原型：
- (NSString *)ioctl:(RequestCmdID)request withData:(NSString *)data;
参数说明：
| 参数 | 说明 | 必要性 |
|---|---|---|
| request | 对应向风控系统请求的命令 | 必填 |
| data | 设置信息的附加数据 | 可选，不需要可填nil或者空 |
request值说明：
typedef enum {
// 初始化配置内容，防止初始化失败情况下，客户可以通过服务端请求初始化配置并传递给SDK
Cmd_SetConfigData = 16,
// 客户服务端将check结果传递给SDK，便于执行后续动作
Cmd_SetResponseData = 17,
// 获取服务端设备指纹
Cmd_GetDeviceId = 20,
} RequestCmdID;
返回值：
错误的情况下，返回：unsupported request（不支持的命令）；正确的情况下，返回对应命令的结果。
注意：该接口的返回值类型均为String，对返回值做判断的时候需要注意该值的类型。
不同命令设置方法：
(1) 设置配置信息
向风控 SDK 配置传递从易盾服务器获取到的产品的配置信息（主要适用于风控 SDK 因被黑灰产屏蔽或其他原因导致无法正常获取配置信息的情况）。
示例代码：
[[NTESRiskUniPerception fomentBevelDeadengo] init:@"易盾提供的产品id" callback:^(int code, NSString * _Nonnull msg, NSString * _Nonnull content) {
if (code != 200) {
[self getInitialConfig:content];
}
}];
- (void)getInitialConfig:(NSString *)content {
// 从易盾服务器获取到的产品的配置信息，并设置给风控SDK
// 如果入参为nil或空，则表示查询当前内存中配置版本；如果参数不为空，则表示更新初始化配置
NSString * configData = @"配置信息";
NSString *ret = [[NTESRiskUniPerception fomentBevelDeadengo] ioctl:Cmd_SetConfigData withData: configData];
}
返回值： 返回值为字符串格式的JSON数据：
// s：状态，int类型，只有为0，v 字段的值才有意义;
// v：版本，long类型(8字节)，配置的版本
{"s":0, "v":1130000000003212}
| 返回值 | 说明 |
|---|---|
| s | 0:成功；-1:内存配置加载失败 |
| v | 配置的版本号 |
(2) 设置响应信息
向风控 SDK 配置传递从易盾服务端获取到的命中及响应结果信息，以便 SDK 执行相关处置动作（主要适用于风控 SDK 因被黑灰产屏蔽或其他原因导致无法正常获取响应结果的情况）。
示例代码：
// 从易盾服务端获取相应数据，并设置给风控SDK
NSString *ret = [[NTESRiskUniPerception fomentBevelDeadengo] ioctl:Cmd_SetResponseData withData:[data valueForKey:@"sdkRespData"]];
返回值： 返回值为字符串格式：
| 返回值 | 说明 |
|---|---|
| 0或者-1 | 输入数据格式有误 |
| 1 | 解析成功 |
(3) 获取服务端设备指纹
获取服务端设备指纹，需要在风控后台配置相关配置，请联系技术支持。
示例代码：
NSString *fp = [[NTESRiskUniPerception fomentBevelDeadengo] ioctl:Cmd_GetDeviceId withData:@""];
返回值： 返回值为字符串格式
注意：除以下返回值外，返回为加密后的设备指纹，需要通过上传至服务端进行解密。
| 返回值 | 说明 |
|---|---|
| -1 | SDK未初始化 |
| 2001 | 无服务端设备指纹缓存 |
| 2002 | 设备指纹服务端获取失败 |
| 2003 | 设备指纹服务端校验失败 |
| 2004 | 设备指纹本地获取失败 |
| 2005 | 设备指纹本地校验失败 |
安全通信协议接口
接口用途：
该接口用于对通信数据进行白盒加密和白盒 HMAC 签名，加密和签名的密钥均会被隐藏，攻击者无法获取，从而保障应用/游戏的通信安全。
最新版本接口（V2）更新内容如下：
- 自定义二进制格式，增大分析难度；
- 多重加密，防明文传输；
- 数据将进行校验，防止篡改；
- 支持多算法，一旦加密算法被破解，可及时更新为另一种算法；
- 一次一密，每次加密的密钥都不相同；
- 自定义安全随机数发生器，防止系统随机数接口被篡改，始终生成一样的密钥；
- 防重放攻击；
- 防模拟执行(脱离Android/iOS环境运行)。
接口须知：
- 如需使用该接口，请联系易盾技术支持获取详细说明文档。
模拟点击AI识别
接口用途：
批量的模拟点击极大的影响到游戏的正常运营，特别是工作室的参与，不仅影响到游戏的平台，还影响到游戏方的收入。易盾智能反外挂SDK提供相关的行为检测方案，使用模拟点击行为检测接口时，需要在游戏登录后，并且调用设置用户信息接口，设置roleId等信息后调用。
接口须知：
请在作弊情况较严重的玩法和场景下调用registerTouchEvent和unregisterTouchEvent，开启和关闭点击数据的采集，初次接入建议设置一个玩法和场景id，并同步给易盾，如需接入多个玩法和场景需提前与易盾沟通。 开启registerTouchEvent后，在该场景结束后必须调用unregisterTouchEvent关闭检测逻辑。
（1）开启采集数据
函数原型：
- (void)registerTouchEvent:(NSUInteger)gameplayId andSceneId:(NSUInteger)sceneId;
函数说明
调用该接口后，开始采集点击事件的相关数据。
参数说明：
| 参数名 | 类型 | 说明 |
|---|---|---|
| gameplayId | NSUInteger | 玩法id |
| sceneId | NSUInteger | 场景id |
示例代码：
[[NTESRiskUniPerception fomentBevelDeadengo] registerTouchEvent:1 andSceneId:3];
（2）关闭数据采集
函数原型：
- (void)unregisterTouchEvent;
函数说明
取消点击事件数据采集。
示例代码：
[[NTESRiskUniPerception fomentBevelDeadengo] unregisterTouchEvent];
