网易易盾手游智能反外挂(iOS-OC)接入文档

2022.11.28 13:45:39

    一、隐私说明

    详情请参照网易易盾隐私政策,请放到应用“隐私协议”中。

    二、接入说明

    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];
    
    Online Chat Tel:95163223