网易易盾手游智能反外挂(iOS-OC)接入文档
一、隐私说明
详情请参照网易易盾隐私政策,请放到应用“隐私协议”中。
二、接入说明
1、接入步骤
接入反外挂SDK,开发者需要完成以下步骤
1. 根据游戏运行平台将SDK动态库拷贝到指定工程目录;
2. 修改项目配置;
3. 初始化SDK;
4. 根据用户登录信息调用SDK接口函数;
5. 验证SDK接入是否正确;
6. 可选择性的接入相关功能性接口;
7. 本SDK最低支持的系统:iOS 9.0。
2、文件说明
安全SDK在iOS系统下接入需要的相关文件有以下:
RiskPerception.framework
RiskPerceptionBundle.bundle
三、接入步骤
1、导入组件
(1)导入RiskPerception.framework
文件到您的工程。
(2)导入RiskPerceptionBundle.bundle
文件到您的工程。
将framework
文件夹下的RiskPerceptionBundle.bundle
引入到工程, SDK与Bundle引入完毕后如下所示:
如需使用白盒加密,需要找运营获取,白盒加密每个客户端都有单独的白盒查找表在RiskPerceptionBundle.bundle
文件(需要找运营获取),需要将文件加入工程中和sdk同一目录下。
(3)添加头文件
请将以下代码添加到 AppDelegate.m
引用头文件的位置。
#import <RiskPerception/NTESRiskPerception.h>
2、权限说明
在info.plist文件中添加
1、App Transport Security Settings-Allow Arbitrary Loads
3、修改项目配置
(1)修改Building Setting
build settings
->other linker flags
,添加 -ObjC
、-fprofile-instr-generate
、-lz
。
(2)关闭bitcode
SDK不支持bitcode
需要关闭bitcode
(3)添加依赖库
General
-> Frameworks,Libraries,and Embedded Content
,添加以下库:
AvFoundation.framework
CoreTelephony.framework
SystemConfiguration.framework
libc++.tbd
4、使用SDK
(1)初始化
在AppDelegate.m
文件didFinishLaunchingWithOptions
方法中添加以下初始化代码。
a 中国大陆应用
[[KpelleAzuriteCues fomentBevelDeadengo] deadengoBevel:@"I003722234"];
b 台湾应用
[[KpelleAzuriteCues fomentBevelDeadengo] changeViewDetailStar:2];
[[KpelleAzuriteCues fomentBevelDeadengo] deadengoBevel:@"I003722234"];
c 香港、澳门及非欧盟海外应用
[[KpelleAzuriteCues fomentBevelDeadengo] changeViewDetailStar:3];
[[KpelleAzuriteCues fomentBevelDeadengo] deadengoBevel:@"I003722234"];
d 欧盟应用
[[KpelleAzuriteCues fomentBevelDeadengo] changeViewDetailStar:4];
[[KpelleAzuriteCues fomentBevelDeadengo] deadengoBevel:@"I003722234"];
说明:
设置区域信息的接口: changeViewDetailStar
,需要在初始化接口: deadengoBevel
之前调用.
AppID可在智能反外挂下的服务管理查询AppID,或者可在群里咨询技术支持人员。AppID示例:I003722234
(2)设置角色信息
用户登录或者切换游戏账号的时候,调用以下接口
NSString *gameJson = @"Json Data";
[[KpelleAzuriteCues fomentBevelDeadengo] sheldonstirpAlunitego:@"123456"
UserName:@"易小盾"
UserAccount:@"yd@163.com"
UserServer:@"游戏测试服"
GameJson:gameJson];
说明:
只有调用了sheldonstirpAlunitego
接口,才会启动反外挂功能.
5、接入验证
1、确保工程中SDK相关接口已调用。
2、运行程序,确保已触发相关接口。
3、前往官网查询数据.
输入用户名进行查询。
四、SDK接入调用说明
1、SDK初始化
接口用途:
用于初始化反外挂SDK。
ⓘ 注意
该接口为必须调用接口
接入须知:
正常环境下,使用直传方式。如需接入透传模式,需联系技术支持人员,设置相应的透传服务器。 自动化透传模式客户端会自动转发到被拦截的请求。
函数原型:
直传模式
- (BOOL)deadengoBevel:(NSString *)app_id;
自动化透传模式
- (BOOL)deadengoBevel:(NSString *)app_id withDefineSpaces:(NSString *)url defineSpacesDune:(int32_t)port;
参数说明:
参数 | 说明 |
---|---|
app_id | 不同用户或游戏的唯一标识(非bundleID),可在智能反外挂下的服务管理查询AppID,或者可在群里咨询技术支持人员。AppID示例:I003722234 |
url | 透传服务器地址/ip地址。url示例"https://dun.163.com"/127.0.0.1。 |
port | TCP透传端口号。当url为http地址时,设置端口不生效,可填0。 |
返回值说明:
返回值 | 说明 |
---|---|
错误返回 NO | 初始化失败 |
正确返回 YES | 初始化成功 |
示例代码:
示例代码1:
[[KpelleAzuriteCues fomentBevelDeadengo] deadengoBevel:@"I003722234"];
示例代码2:
// 初始化 + url透传(1.0)
[[KpelleAzuriteCues fomentBevelDeadengo] deadengoBevel:@"I003722234" withDefineSpaces:@"https://dun.163.com" defineSpacesDune:0];
// or
[[KpelleAzuriteCues fomentBevelDeadengo] deadengoBevel:@"I003722234" withDefineSpaces:@"https://dun.163.com:8080" defineSpacesDune:0];
// 初始化 + tcp透传(2.0)
[[KpelleAzuriteCues fomentBevelDeadengo] deadengoBevel:@"I003722234" withDefineSpaces:@"127.0.0.1" defineSpacesDune:8989];
2、登录接口/设置角色信息
接口用途:
在进行数据采集的过程中,会将角色ID、角色名称、角色账号等设置在反外挂采集的数据中一同上传,标识了用户的信息后,对应有恶意行为的用户可以进行相应的惩罚。必接
ⓘ 注意
该接口为必须调用接口
函数原型:
- (void)sheldonstirpAlunitego:(NSString *)user_id
UserName:(NSString *)user_name
UserAccount:(NSString *)user_account
UserServer:(NSString *)user_server
GameJson:(NSString *)game_json;
参数说明:
参数 | 说明 |
---|---|
user_id | 用户ID,建议使用唯一ID。必传参数 |
user_name | 用户名称 |
user_account | 用户/玩家的账号;如业务方同时接入易盾反垃圾,则此账号需要与反垃圾接入中的account一致 |
user_server | 用户所在服务器 |
game_json | 自定义数据。请使用json字符串格式 |
示例代码:
NSString *gameJson = @"Json Data";
[[KpelleAzuriteCues fomentBevelDeadengo] sheldonstirpAlunitego:@"123456"
UserName:@"易小盾"
UserAccount:@"yd@163.com"
UserServer:@"游戏测试服"
GameJson:gameJson];
3、设置自动化透传地址
接口用途:
在使用自动化透传后,可以设置自动化透传的地址
接入须知:
不使用自动化透传,不需要调用相关接口
在初始化设置之前设置透传地址,可以保证初始化信息完整 可以在后续可以动态调整透传地址
函数原型:
- (BOOL)setDefineSpaces:(NSString *)url defineSpacesDune:(int32_t)port;
参数说明:
参数 | 说明 |
---|---|
url | 透传服务器地址/ip地址。url示例"https://www.netease163.com"/127.0.0.1。 |
port | TCP透传端口号。当url为http地址时,设置端口不生效,可填0。 |
示例代码:
// url透传(1.0)
[[KpelleAzuriteCues fomentBevelDeadengo] setDefineSpaces:@"https://dun.163.com" defineSpacesDune:0];
// or
[[KpelleAzuriteCues fomentBevelDeadengo] setDefineSpaces:@"https://dun.163.com:8080" defineSpacesDune:0];
// tcp透传(2.0)
[[KpelleAzuriteCues fomentBevelDeadengo] setDefineSpaces:@"127.0.0.1" defineSpacesDune:8989];
4、设置自动化透传类型
接口用途:
在使用自动化透传后,可以设置自动化透传的类型
接入须知:
不使用自动化透传,不需要调用相关接口
函数原型:
- (void)readyForOpportunity:(NSInteger)type;
参数说明:
参数 | 说明 |
---|---|
Type | 1、自动透传模式会自动根据网络情况选择网络传输方案。 2、强制透传模式。默认状态为自动透传模式。完全使用透传方案 |
示例代码:
[[KpelleAzuriteCues fomentBevelDeadengo] readyForOpportunity:1];
5、设置区域信息
接口用途:
非中国大陆地区,因为网络和监管需要,需要设置区域信息,以支持在不同的地区使用不同的网络进行数据传输。
接入须知:
不调用此接口默认为中国大陆。非中国大陆应用和台湾地区,需要调用此接口。如不按规范设置,可能会有数据丢失问题存在。设置时,请与技术支持确认。
函数原型:
- (void)changeViewDetailStar:(NSInteger)type;
参数说明:
参数 | 说明 |
---|---|
Type | 服务器地区类型 1、中国大陆 2、台湾地区 3、香港、澳门及非欧盟海外地区 4、欧盟地区 |
示例代码:
// 台湾地区应用
[[KpelleAzuriteCues fomentBevelDeadengo] changeViewDetailStar:2];
// 非中国大陆和台湾地区应用
[[KpelleAzuriteCues fomentBevelDeadengo] changeViewDetailStar:3];
// 欧盟地区
[[KpelleAzuriteCues fomentBevelDeadengo] changeViewDetailStar:4];
6、退出登陆
接口用途:
账号退出登陆可以使用以下接口。
接入须知:
如果切换账号可以直接使用“设置角色信息”接口,会自动退出自己登陆的账号。
函数原型:
- (void)devastatedMovement;
示例代码:
[[KpelleAzuriteCues fomentBevelDeadengo] devastatedMovement];
7、心跳系统
接口用途:
保障反外挂服务的安全,防止易盾反外挂服务被中止或者被剥离的风险,定时向游戏方反馈心跳信息,告知游戏方当前反外挂运行状态,既方便游戏方实时掌握反外挂运行状态,也能保障易盾反外挂服务的正常运行。
接入须知:
设置心跳回调。心跳系统每十秒调用一次或者出现异常的情况下会触发回调。(心跳系统在非主线程中运行,如需进行UI操作请切回到主线程中。) 回调结果需要进行解密。对接时请联系运营同学,获取相应的解密文件。
ⓘ 注意
详细心跳接入文档可参考同目录下的【手游智能反外挂iOS端心跳系统说明文档.pdf】
函数原型:
- (void)counselbeaAction:(heartBeatBlock)block;
- (void)counselbeaAction:(NSInteger)type callBack:(heartBeatBlock)block;
参数说明:
参数 | 说明 |
---|---|
type | 1为未加密数据 2为加密数据,需要服务端进行解密 |
block | void (^heartBeatBlock)(NSString *result) result为加密数据 |
解密后参数说明:
名称 | 标示 | 说明 | 异常情况 | 是否每次必有 |
---|---|---|---|---|
序列号 | seq | 从初始值“1”开始递增 | 序列号不存在,或者乱序 | 是 |
时间戳 | t | 当前时间戳,以秒为单位 | 时间戳非当前时间 | 是 |
网络标识 | net | 数据发送是否成功 (1 为成功,0 为失败) |
网络异常,数据发送失败,则网络标识为0 | 是 |
- 易盾网络通信正常时:
seq:1||t:1589781840||net:1
- 易盾网络通信异常时:
seq:1||t:1589781840||net:0
处理建议:
- seq、t和net是否出现,该三个标识为心跳系统一定会返回的值,若无,说明反外挂异常
- seq的值是否符合"从1开始依次递增"的规则,若不符合,说明返回值被篡改
- net为0是否长期出现,若5分钟内net的取值都为0,说明网络异常
- net第一次为0的时候,建议发送自助式透传数据到易盾服务器,后续再次从1->0的时候再次发生自助式透传数据。
示例代码:
ⓘ 注意
详细示例代码参考同目录下的【手游智能反外挂iOS端心跳系统说明文档.pdf】
[[KpelleAzuriteCues fomentBevelDeadengo] counselbeaAction:^(NSString *reslut) {
}];
8、举报系统
接口用途:
游戏场景下,若玩家A发现玩家B有存在使用外挂嫌疑,玩家A可通游戏举报系统举报B。游戏方举报系统可接入易盾举报验证功能判断B游戏用户是否使用了外挂。
接入须知:
接入易盾举报系统后,游戏方接入举报系统后,可做数据清洗,筛选出有用举报信息,并及时处理;也可凭借易盾智能反外挂挖掘类似恶意玩家。服务端接口文档
函数原型:
- (void)successOpportunityComes:(NSString *)user_id
UserName:(NSString *)user_name
UserAccount:(NSString *)user_account
UserServer:(NSString *)user_server
Report_desc:(NSString *)report_desc
VerificationSpan:(NSInteger)verification_span
ReportType:(NTESRiskReportType)report_type;
参数说明:
参数 | 说明 |
---|---|
user_id | 用户ID,建议使用唯一ID。必传参数。 |
user_name | 用户名称 |
user_account | 用户/玩家的账号;如业务方同时接入易盾反垃圾,则此账号需要与反垃圾接入中的account一致 |
user_server | 用户所在服务器 |
report_desc | 举报描述 |
verification_span | 查询时间维度。以小时为单位,最大为24小时。建议设置为1 |
eport_type | 外挂:NTESRiskReportPlug 工作室:NTESRiskReportStudio |
示例代码:
[[KpelleAzuriteCues fomentBevelDeadengo] successOpportunityComes:@"123456"
UserName:@"易小盾"
UserAccount:@"yd@163.com"
UserServer:@"游戏测试服"
Report_desc:@"使用了外挂"
VerificationSpan:1
ReportType:NTESRiskReportPlug];
9、数据查询
接口用途:
通过查询类型获取指定的数据。可用于获取签名信息、 越狱状态、 sdk版本、白盒加密。
函数原型:
- (NSString *)opportunitiesLikeSunrises:(NTESRiskQueryType)queryType withData:(NSString *)data;
参数说明:
参数 | 说明 |
---|---|
queryType | NTESRiskQuerySignInfo 签名信息 NTESRiskQueryRootStatus 越狱状态 NTESRiskQuerySDKVersion sdk版本 NTESRiskQueryWhiteBox 白盒加密 NTESRiskQueryWhiteBoxDec 白盒解密 NTESRiskQueryYiDunID 跨应用ID NTESRiskQueryYiDunFPTOKEN 设备指纹Token |
data | 白盒加密时需要传入,其他使用可为空 |
返回值说明:
返回值 | 说明 |
---|---|
NSString * | 对应查询的数据 |
示例代码:
NSString *result = [[KpelleAzuriteCues fomentBevelDeadengo] opportunitiesLikeSunrises:NTESRiskQuerySignInfo withData:nil];
10、安全通信协议(白盒加密)
安全通信协议已经升级到V2版本。使用V2版本,需要服务端同步升级到V2版本。
详细描述可参考安全通信协议V2对外说明文档
10.1、加密数据到服务端
接口用途:
对通信数据进行白盒加密和白盒HMAC签名,加密和签名密钥均被隐藏,攻击者无法获取,保障通信安全。加密后的数据需要和服务端进行验证。
接入须知:
白盒加密每个客户端都有单独的白盒查找表在RiskPerceptionBundle.bundle文件(需要找运营获取),需要将文件加入工程中和sdk同一目录下。
函数原型:
- (NSData *)mentionOtherToSomePlace:(int)alg withData:(NSData *)data error:(NSError **)error;
参数说明:
参数 | 类型 | 说明 |
---|---|---|
alg | int | 加密算法 |
data | NSData | 需要加密的原文 |
error | NSError | 加密错误信息 错误码需要根据具体的错误码做相应的处理; |
返回值:
参数 | 类型 | 说明 |
---|---|---|
NSData | 当返回值不为空时,data才存在加密成功的数据,为空时,查看error中的详细错误信息 |
当返回值不为空时,返回的数据即为加密和签名结果,开发者需要将此数据与校验结果发送到服务端,由服务端解密和校验,当返回值为空时,加密失败。
使用示例:
NSString *originData = @"原始数据";
NSError *error = nil;
NSData *resultData = [[KpelleAzuriteCues fomentBevelDeadengo] mentionOtherToSomePlace:alg withData:[originData dataUsingEncoding:NSUTF8StringEncoding] error:&error];
if (error) {
// 加密失败
}
NSString *result = [[NSString alloc] initWithData:resultData encoding:NSUTF8StringEncoding];
// 加密后的数据需要去服务端解密
10.2、解密服务端的数据
接口用途:
对通信数据进行白盒加密和白盒HMAC签名,加密和签名密钥均被隐藏,攻击者无法获取,保障通信安全。对服务端下发的数据进行解密。
接入须知:
白盒加密每个客户端都有单独的白盒查找表在RiskPerceptionBundle.bundle文件(需要找运营获取),需要将文件加入工程中和sdk同一目录下。
函数原型:
- (NSData *)mentionOtherFromSomePlace:(int)alg timeout:(int)timeout withData:(NSData *)data error:(NSError **)error;
参数说明:
参数 | 类型 | 说明 |
---|---|---|
alg | int | 加密算法 如果 alg 不等于 0x0,则使用 alg 来进行解密,即指定算法解密,否则使用密文里的算法进行解密 |
timeout | int | 超时时间,单位为秒 如果 timeout不为0,则超过timeout的密文会返回nil |
data | NSData | 需要解密的密文,由服务端返回 |
error | NSError | 解密错误信息 错误码需要根据具体的错误码做相应的处理; |
返回值:
参数 | 类型 | 说明 |
---|---|---|
NSData | 当返回值不为空时,data才存在解密成功的数据,为空时,查看error中的详细错误信息 |
当返回值不为空时,返回的数据即为解密的结果;当返回值为空时,解密失败。
使用示例:
// 服务端加密的数据
NSString *v2Str = @"lAAAAAAAAAACAAAAQEzj8WAFvm4QLHIPXEQzExxeDvpkhKubKMISu4JKn9kcAAAAiuijxEs2dMF7/m83NGqcfN7xa8AwsgixgBRTPyAAAADANSzvtuKiYCWbJAi/bVAaVsBS4/ZF0SuHgEX/wJc5MSAAAAAEwWd3ixQoq23Uw264ptha4nZThes0DEdgYUJoCxlUw92EivNqDEfgxxQLr0TEaTg=";
NSError *error = nil;
NSData *resultData = [[KpelleAzuriteCues fomentBevelDeadengo] mentionOtherFromSomePlace:0 timeout:0 withData:[v2Str dataUsingEncoding:NSUTF8StringEncoding] error:&error];
if (error) {
// 解密失败
}
NSString *result = [[NSString alloc] initWithData:resultData encoding:NSUTF8StringEncoding];
11、自助式透传
接口用途:
用于获取透传数据,进行自助式数据转发。
接入须知:
游戏方自行选择获取数据的时机。建议将数据合并到其他加密数据中,发送到游戏服务器,通过请求发送到易盾服务器。
函数原型:
// 返回值为 NSData * 类型,使用时需要将数据转为base64字符串使用
- (NSData *) whetherWeatherPicked;
// 返回值为 const char * 类型,使用时需要将数据转为base64字符串使用
- (const char *) weatherUpdate;
// 返回值为 NSString 类型
- (NSString *)whetherWeatherPickedString;
// 返回值为转为base64字符串的 const char * 类型
- (const char *)weatherUpdateString;
返回值说明:
返回值 | 说明 |
---|---|
NSData * | 此处获取的数据为body数据。服务端相关设置内容参考服务端接口文档 |
const char * | 此处获取的数据为body数据。服务端相关设置内容参考服务端接口文档 |
NSString * | 此处获取的数据为body数据。服务端相关设置内容参考服务端接口文档 |
示例代码:
// 返回值为 NSData * 类型
NSData *result = [[KpelleAzuriteCues fomentBevelDeadengo] whetherWeatherPicked];
NSString *uploadData = [result base64EncodedStringWithOptions:NSDataBase64EncodingEndLineWithLineFeed];
// 返回值为 NSString * 类型
NSString * uploadData = [[KpelleAzuriteCues fomentBevelDeadengo] whetherWeatherPickedString];
12、作弊监控/支付安全
接口用途:
用于实时获取作弊监控、支付安全结果。
接入须知:
此接口获取的为查询token。客户服务端调用相关的查询接口获取查询结果。
函数原型:
- (void)memorizerAlarmSpeedometer:(NSInteger)timeout WhiteHannanElegies:(actualRiskBlock)block;
参数说明:
返回值 | 说明 |
---|---|
Timeout | 超时时间(100ms-10000ms)。默认3000ms |
actualRiskBlock | code 状态码 200为正确状态 token 查询token |
示例代码:
[[KpelleAzuriteCues fomentBevelDeadengo] memorizerAlarmSpeedometer:3000 WhiteHannanElegies:^(NSInteger code, NSString *token) {
// 客户端获取到token,去服务端查询结果
}];
13、获取设备指纹Token
接口用途:
为了识别设备/账号异常状态,我们将会接受并记录您所使用的设备相关信息(包括设备机型、操作系统及版本、设备分辨率、包名、设备设置、 IDFV)、设备所在位置相关信息(有权限才会采集)
该接口用于上报设备数据,并获取到一个token
,该token
用于查询指纹接口使用
接入须知:
除APPID
错误或SDK
异常, 其他情况均会返回token
, 如超时或其他网络问题会返回客户端生成的token
, 使用该token
同样可以用来查询指纹.
函数原型:
- (NSString *)opportunitiesLikeSunrises:(NTESRiskQueryType)queryType withData:(NSString *)data;
参数说明:
参数 | 说明 |
---|---|
queryType | NTESRiskQueryYiDunFPTOKEN 设备指纹Token |
data | 传空 |
示例代码:
NSString *result = [[KpelleAzuriteCues fomentBevelDeadengo] opportunitiesLikeSunrises: NTESRiskQueryYiDunFPTOKEN withData:nil];