手游智能反外挂Android端接入文档(C/C++)

2024.03.14 20:19:08

    隐私说明

    请参照网易易盾隐私政策,请将易盾隐私政策链接放到应用“用户协议”中。

    接入说明

    接入反外挂SDK,开发者需要完成以下步骤

    1. 根据游戏开发平台将SDK拷贝到指定工程目录;
    2. 修改项目配置;
    3. 初始化SDK;
    4. 根据用户登录信息调用SDK接口函数;
    5. 验证SDK接入是否正确;
    6. 可选择性的接入相关功能性接口;
    7. 单独付费功能接入前需与易盾联系。
    8. 本sdk最低支持的系统为Android 4.4
    

    注意:

    必须接入接口:初始化登录接口透传服务

    强烈建议接入接口:通用查询接口的反外挂运行状态

    建议接入接口:心跳系统安全通信协议

    接入步骤

    SDK涉及到的文件有以下:

    nethtprotect.jar
    htp_agent.h
    htp_sdk.h
    htp_sdk.cpp
    libNetHTProtect.so
    assets/motion/XXX
    assets/isc73f69dca5b.zip
    

    引入jar

    在工程内添加对nethtprotect.jar的依赖

    引入so

    在 android 工程加载游戏 so 的地方,添加对libNetHTProtect.so 的引用。

    public class Game {
        static {
            System.loadLibrary("NetHTProtect");
            System.loadLibrary("game");
        }
    } 
    

    注意:libNetHTProtect.so的加载顺序,需要在游戏自己的 so 之前。

    链接so

    在 jni/android.mk 中添加如下代码,用于链接libNetHTProtect.so

    include $(CLEAR_VARS)
    LOCAL_MODULE := libNetHTProtect
    LOCAL_SRC_FILES := $(TARGET_ARCH_ABI)/libNetHTProtect.so
    include $(PREBUILT_SHARED_LIBRARY)
    

    在 jni/Android.mk 中,游戏所在的 so 节,添加如下代码,用于指示对 libNetHTProtect 的引用

    LOCAL_SHARED_LIBRARIES += libNetHTProtect
    

    添加权限信息

    SDK不会申请任何权限,但是为了提升反外挂的效果,建议在AndroidManifest.xml文件中添加下列权限配置:

        <!--网络通信-->
        <uses-permission android:name="android.permission.INTERNET"/>
        <!--获取设备信息-->
        <uses-permission android:name="android.permission.READ_PHONE_STATE" />
        <!--获取MAC地址-->
        <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
        <!--获取网络状态-->
        <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    
        <!--若App的targetSdkVersion>=30,则需要增加以下权限,否则会影响SDK功能。-->
        <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" />
    

    添加ProGuard配置

    若使用ProGuard进行混淆,需要将SDK使用的类排除掉。若使用Android Studio开发,则在proguard-rules.pro文件里添加如下信息:

     -keep class com.netease.htprotect.**{*;}
     -keep class com.netease.mobsec.**{*;}
    

    SDK初始化

    接口用途:

    用于初始化反外挂SDK。

    接入须知:

    使用其他接口之前,必须先调用初始化接口,建议在游戏启动后第一时间调用。

    注意:

    该接口为必须调用接口

    函数原型:

    void htp_init(const char *appid, const char *game_key,int serverType); 
    
    参数说明:
    参数 说明
    appid 易盾HTP分配appId,可登录易盾后台获取
    game_key 易盾HTP分配gameKey,与手游加固的appKey对应,gameKey可登陆易盾后台获取
    serverType 默认值为1;中国大陆地区请填1;中国台湾地区请填2;其他地区请填3;欧盟地区请填4

    如需要示例demo请联系易盾获取。

    登录接口、登出接口

    登录接口:

    接口用途:

    在进行数据采集的过程中,会将角色ID、角色名称、角色账号等设置在反外挂采集的数据中一同上传,标识了用户的信息后,对应有恶意行为的用户可以进行相应的惩罚。

    接入须知:

    须在init接口被调用后,且用户同意隐私政策后才能调用该接口,涉及到玩家登陆或者切换角色的地方,均需要调用该接口设置或者更新角色信息。

    注意:

    该接口为反外挂业务必须调用接口,且用户同意隐私政策后才能调用该接口,网易易盾隐私政策

    函数原型:
    void htp_set_role_info(const char* role_id, const char* role_name, const char* role_account, const char* role_server, const char* game_json);
    
    参数说明:
    参数 说明 赋值
    roleId 玩家的角色ID 必填
    roleName 玩家的角色名称 可填空
    roleAccount 玩家的角色账号;如业务方同时接入易盾反垃圾,则此账号需要与反垃圾接入中的account一致 可填空
    roleServer 玩家的角色服务器 可填空
    serverId 所属服务器的id 可填空
    gameJson 游戏需要上传的信息,对应一个json字符串,包含key 可填空

    gameJson字段说明:

    KEY名称 KEY类型 KEY值 是否必须 官网标识 说明
    游戏版本号 字符串 GameVersion 可选 游戏版本
    资源版本号 字符串 AssetVersion 可选 资源文件版本
    数据转发域名 字符串 TransHost 可选 易盾网络不通时,反外挂数据转发域名地址,需要设置“http://”或者“https://”前缀,如果没有设置,默认按http补充(接入透传时使用)
    数据转发IP 字符串 TransIP 可选 易盾网络不通时,会通过输入的ip地址进行tcp通信(接入透传时使用)
    数据转发端口 int TransPort 可选 输入的ip对应的端口号(接入透传时使用)

    数据转发域名/端口:
    设置之后,当数据发送到易盾后端失败后,会继续向游戏服务端发送数据,由游戏方服务端转发到易盾后端.域名可以选择设置一个或者都设置,端口默认使用80。此字段设置前需要和易盾技术人员确定。尽量默认接入的时候带上,之后有需要再搭建服务端转发,数据转发只会在发送到易盾服务端失败的情况下会走转发流程。

    登出接口:

    接口用途:

    为了更好地统计该角色在本次登录后的行为,更精确地标识和打击有恶意行为的用户。

    接入须知:

    须在init接口被调用后方可调用,在用户退出本角色(包括切换角色)或者退出游戏时,需要调用该接口通知反外挂SDK。

    函数原型:
    void htp_logout();
    

    作弊监控(单独付费功能)

    5.2.10.9之后不再支持,若需使用请升级到智能风控。

    作弊监控用于注册、登录保护、营销反作弊等场景,与反外挂是相互独立业务,可单独接入。

    接口用途:

    用于可能被批量利用的业务场景里,比如登录、注册、领取奖励、抽卡等情况,业务方可通过该功能,判断当前玩家实时状态。业务客户端可通过该接口获取token,并将该token发送到业务方服务端,然后由业务方服务端向易盾服务端发起check请求,获取玩家当前检测结果,业务方服务端根据该结果做出相应操作。

    接入须知:

    通过该接口获取唯一凭证token,业务方客户端需要将此token提交到业务后端,业务后端再使用此token来请求check接口获取检测结果,作弊监控(服务端)接入文档

    注意:

    该接口为同步接口,会有一定的耗时,默认超时时间为3s须在SDK初始化登录接口/设置角色信息被调用后,且用户同意隐私政策后才能调用该接口网易易盾隐私政策

    若注册保护场景,当前无角色信息,可设置“roleId”为“0”,登录接口/设置角色信息调用的目的是告知sdk已同意隐私政策,可获取mac等隐私信息。

    因为数据上报可能存在延迟,请确保在setRoleInfo接口调用3秒以后,再调用getToken

    函数原型:
    int htp_getToken(/*[out]*/char* buf, size_t size, /*[out]*/size_t *used_buf_size);
    
    参数说明:
    参数 说明
    buf 返回数据buffer
    size 返回数据buffer大小
    used_buf_size 实际使用的buffuer大小
    返回值:

    正常情况下,返回的buf里面,一定包含有token的值,只有一种情况会返回空,init接口调用失败;init接口失败目前只有一种情况:未开通作弊监控服务。

    模拟点击行为检测(单独付费功能)

    接口用途:

    批量的模拟点击极大地影响到游戏的运行,特别对工作室的参与,不仅影响到游戏的平台,还影响到游戏方的收入。易盾智能反外挂SDK提供了相关的行为检测方案。使用模拟点击行为检测接口时,需要在游戏登录后,并且调用登录接口/设置角色信息,设置role_id等信息后调用。

    接入须知:

    非强烈需要挖掘模拟点击类外挂的游戏,不需要接入。

    请在作弊情况较严重的玩法和场景下调用registerTouchEvent和unregisterTouchEvent,开启和关闭点击数据的采集,初次接入建议设置一个玩法和场景id,并同步给易盾,如需接入多个玩法和场景需提前与易盾沟通。

    使用该功能的时候,需要将SDK内提供的assets目录下文件的全部拷贝到APK的assets目录下。

    (1)开启采集数据

    函数原型:
    void htp_register_touchevent(int gameplayId, int sceneId)
    
    函数说明:

    调用该接口后,开始采集点击事件的相关数据。

    参数说明:
    参数 说明
    gameplayId 玩法id
    sceneId 场景id

    (2)关闭数据采集

    函数原型:
    void htp_unregister_touchevent()
    
    函数说明:

    取消点击事件数据采集。

    通用查询

    接口用途:

    反外挂SDK提供root、模拟器、反外挂版本等信息查询服务,以及其他定制功能。

    接入须知:

    必须在setRoleInfo之后才可调用该接口

    函数原型:
    int htp_ioctl(int request, const char* data, /*[out]*/char* buf, size_t size, /*[out]*/size_t *used_buf_size);
    
    参数说明:
    参数 说明
    request 对应向反作弊模块请求的命令
    data 对应设置信息的附加数据,可为空
    buf 返回数据buffer
    size 返回数据buffer大小
    used_buf_size 实际使用的buffuer大小

    request值:

    enum RequestCmdID {
        Cmd_GetEmulatorName = 1,
        Cmd_IsRootDevice = 2,
        Cmd_DeviceID = 3,
        Cmd_GetHTPVersion = 7,
        Cmd_GetCollectData = 8,//建议在子线程调用此接口
        Cmd_GetEncHTPVersion = 9,
        Cmd_GetHtpStatus = 14,
        Cmd_GetFpToken = 15
    };
    
    返回值:

    错误返回 unsupported request (不支持的命令),正确返回对应命令的结果

    心跳系统

    接口用途:

    保障反外挂服务的安全,防止易盾反外挂服务被中止或者被剥离的风险,定时向游戏方反馈心跳信息,告知游戏方当前反外挂运行状态,既方便游戏方实时掌握反外挂运行状态,也能保障易盾反外挂服务的正常运行。

    同时也可通过心跳实时返回反外挂数据,如需要详细说明文档,请联系易盾获取。

    接入须知:
    • registInfoReceiver接口需要在init之后方可调用
    • SDK会启动线程来调用onReceive函数,请注意多线程问题
    函数原型:
    void htp_register_info_receiver(IInfoReceiver* receiver);
    
    参数说明:
    参数 类型 说明
    receiver IInfoReceiver 回调函数,接收心跳信息

    InfoReceiver的接口定义:

    #ifdef __cplusplus
    class IInfoReceiver
    {
    public:
        virtual ~IInfoReceiver(){}
        virtual void onReceive(int InfoType, const char* info) = 0;
    };
    #endif
    
    onReceive参数说明:
    参数 类型 说明
    Type int 接收数据的类型
    Info const char* 接收的具体数据

    目前支持的type类型有:

    定义 说明
    1 INFO_TYPE_HEARTBEAT 心跳数据,可直接在客户端解析
    2 INFO_TYPE_ENC_HEARTBEAT 加密后的心跳数据,必须发往服务端进行解密
    3 INFO_TYPE_CHEATINFO 检测信息,包括app基本信息以及检测到的异常信息

    注:两种type类型均可接收,也可只接收其中一种,建议只获取加密后的心跳数据,然后发往服务端进行解析。

    心跳系统是每10s内会返回一次数据("Info"),返回的数据为一个字符串,"Info"包含三种信息,分别是序列号、时间戳、网络状态,使用"key:value"格式并使用“||”分割,含义如下表所示:

    名称 标示 说明 异常情况 是否每次必有
    序列号 seq 从初始值“1”开始递增 序列号不存在,或者乱序
    时间戳 t 当前时间戳,以秒为单位 时间戳非当前时间
    网络标识 net 数据发送是否成功
    (1 为成功,0 为失败)
    网络异常,数据发送失败,则网络标识为0

    Info的返回值示例:

    • 易盾网络通信正常时:
    seq:1||t:1589781840||net:1
    
    • 当易盾网络通信异常时:
    seq:1||t:1589781840||net:0
    

    处理建议:

    • seq、t和net是否出现,这三个标识为心跳系统一定会返回的值,若无,说明反外挂异常
    • seq的值是否符合"从1开始依次递增"的规则,若不符合,说明返回值被篡改
    • net为0是否长期出现,若5分钟内net的取值都为0,说明网络异常
    • 若出现反外挂异常或网络异常,请结合游戏业务数据综合判断并自行处理

    数据校验

    接口用途:

    游戏协议如被破解,若为单机游戏,可直接影响到存档文件的安全性;若为帧同步游戏,则可通过破解协议修改战斗数据;其他类型游戏亦可被做成脱机协议,用于攻击或脱机外挂。为保障游戏协议安全,易盾提供“数据校验”方案,采用自研通讯协议校验算法。

    接入须知:

    客户端接入数据校验接口后,服务端对对应的数据进行校验,服务端数据校验相关文档请联系易盾获取。

    函数原型:
    int htp_get_data_sign(int alg_type, const char* data, /*[out]*/char* buf, size_t size, size_t* used_buf_size);
    
    参数说明:
    参数 说明
    alg_type 表示算法标识,需要联系易盾人员
    data 待校验的数据
    buf 返回的数据即为校验结果,开发者需要将原始数据与校验结果发送到游戏服务端,由游戏服务端校验
    size 返回数据大小
    used_buf_size 实际使用数据的大小
    返回值:

    返回的数据即为校验结果,开发者需要将原始数据与校验结果发送到游戏服务端,由游戏服务端校验。

    安全通信协议

    对通信数据进行白盒加密和白盒HMAC签名,加密和签名密钥均被隐藏,攻击者无法获取,保障通信安全。

    新版本更新如下:

    • 自定义二进制格式,增大分析难度
    • 多重加密,防明文传输
    • 带校验,防篡改
    • 多算法,一旦加密算法被破解,可及时更新为另一种算法
    • 一次一密,每次加密的密钥都不相同
    • 自定义安全随机数发生器,防止系统随机数接口被篡改,始终生成一样的密钥
    • 防重放攻击
    • 防模拟执行(脱离Android/iOS环境运行)
    接入须知:

    如需调用此接口,请联系易盾获取相关资料

    存档加解密

    接口用途:

    对需要本地存储的数据提供加解密功能

    接入须知:

    加密后的数据,需要接入方自行存储,sdk只提供加密和解密功能

    函数原型:

    加密对象为String:

    int htp_enc_local(const char* buf, size_t size, /*[out]*/char* enc_buf, size_t enc_buf_size, /*[out]*/size_t *used_buf_size,int alg_type);
    int htp_dec_local(const char* buf, size_t size, /*[out]*/char* dec_buf, size_t dec_buf_size, /*[out]*/size_t *used_buf_size,int alg_type);
    
    参数说明:
    参数 说明
    buf 需要加密或者解密的数据
    size buf的大小
    enc_buf/dec_buf 返回数据buffer
    enc_buf_size/dec_buf_size 返回数据buffer大小
    used_buf_size 实际使用的buffuer大小
    alg_type 参数为0:跟app安装绑定;参数为1:跟app签名绑定

    返回值:

    若是加密接口,返回的数据即为原始数据的密文。

    若是解密接口,返回的数据即为密文对应的原始数据。

    透传服务

    随着外挂和恶意环境对抗的不断升级,部分外挂玩家使用工具屏蔽网易易盾域名和ip,阻断反外挂策略更新,影响反外挂效果,特别是云真机玩家,部分云真机自动屏蔽网易易盾域名。若游戏方需要检测云真机环境或者外挂对抗较为激烈建议接入透传服务。

    接入须知:

    客户端接入方式:在玩家登录游戏后,在通用查询中,设置RequestCmdID为Cmd_GetCollectData,获取反外挂嫌疑数据,然后(可与游戏数据一起)上报到游戏服务器,游戏服务端再将反外挂嫌疑数据发送到易盾服务器。

    服务端接入方式:游戏方自助式透传

    在线咨询 电话咨询:95163223 免费试用