C++接入教程

2024.03.28 14:08:10

    隐私说明

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

    接入说明

    接入“智能风控” SDK,开发者需要完成以下步骤:

    1. 根据应用/游戏开发平台,将SDK拷贝到指定的工程目录,并修改项目配置;
    2. 接入风控SDK必接接口,根据业务需求接入建议接口;
    3. 测试风控SDK接入是否正确;
    4. 验证风控SDK功能效果;
    5. 按业务常规发版流程进行测试与发版
    

    游戏必须接入:

    建议接入:

    接入步骤

    请登录易盾官网后台风控引擎-服务管理获取SDK,详情如图。image title

    SDK 涉及到以下文件:

    nethtprotect.jar
    libNetHTProtect.so
    assets/motion/xxx.so
    htp_agent.h
    htp_sdk.cpp
    htp_sdk.h
    

    注意:

    打包出来的 apk,必须包含 lib/xxx/libNetHTProtect.so 与 assets/motion/ 下的所有so文件。

    引入jar

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

    引入so

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

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

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

    引入htp_sdk

    htp_agent.h htp_sdk.h htp_sdk.cpp 导入到项目中,在需要使用反外挂sdk函数的cpp中,引入 htp_sdk.h 头文件

    链接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 不会申请任何权限,但是为了提升风控的效果,建议在 AndroidMenifest.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"/>
        <!--若targetSdkVersion>=30,则需要增加以下权限,否则会影响SDK功能-->
        <queries>
            <intent>
                <action android:name="android.intent.action.MAIN"/>
            </intent>
        </queries>
    

    添加 ProGuard 配置

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

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

    SDK 接入调用说明

    重要:如果是在子线程调用反外挂的接口,请务必在子线程开始处调用 AndroidJNI.AttachCurrentThread() ,并且在子线程结束前调用 AndroidJNI.DetachCurrentThread() ,否则会发生内存泄漏或崩溃。

    部分产品相关参数请用账号登录易盾官网控制台获取参考image title

    SDK 初始化接口(init)

    接口用途:

    用于初始化智能风控 SDK。

    接入须知:

    1. 使用其他接口之前,必须先调用初始化接口(init),建议在应用/游戏启动过后第一时间调用(初始化后,并不会获取任何个人隐私相关信息);
    2. 该接口为 必须调用接口

    函数原型:

    void htp_init(const char *productid, const GameSetInfo &info, CallBack cb);
    

    参数说明:

    参数 说明 必要性
    productId 易盾HTP分配的productId,可登录易盾后台获取 必填
    info 与HTP相关的一些配置信息 可选,不需要可填null
    cb 初始化是否成功的回调 可选,不需要可填null
    GameSetInfo结构体
    struct GameSetInfo {
        std::string game_key;            //由易盾分配
        int server_type;                 //服务端所属地区
        std::string channel;             //渠道信息
        std::map<std::string ,std::string> ext_data;            //额外数据
    }
    
    字段 说明
    game_key 由易盾分配gameKey,可登录易盾后台获取。数据校验存档加解密必须设置此值,如果不使用这三个功能,可不设置或置空,可以自定义32位长度字符串
    server_type 服务器归属地,反外挂默认上报的服务器为中国大陆,若需要更改服务器归属地,可以调用该接口进行配置,支持的类型如下:1:中国大陆地区,默认即为该值,无须设置;2:中国台湾地区;3:海外地区
    channel 渠道信息
    ext_data 额外数据,作弊监控接口需要,可设置一些额外信息,必须在init之前设置

    示例

    GameSetInfo info;
    info.server_type = 1; // 服务器所在地址,1:中国大陆,2:中国台湾地区,3:其他地区,4:欧盟地区
    info.channel = "testchannel"; // 渠道
    info.game_key = "fed80c732b7b467ea2156c29f830eed24fc8"; // 易盾HTP分配的gameKey
    std::map<std::string, std::string> ext_data;
    ext_data["c"] = "1";
    ext_data["e"] = "11Y=";
    ext_data["i"] = "222";
    info.ext_data = ext_data; // 额外信息,反作弊接口需要,可不设置
    
    CallBack回调

    CallBack为一个函数指针,定义如下

    typedef int(*CallBack)(int, const char*);
    

    在使用时,需自己实现一个相同参数的函数,比如

    /**
     * 初始化的回调接口
     * @param code 回调接口返回的错误码
     * @param msg 回调接口返回的信息
     * @return
     */
    int htp_init_callback(int code, const char* msg) {
        LOGD("code = %d msg = %s", code, msg);
        // 如果code == 200,说明反外挂一切正常
        // 如果code == 400,请将 msg发送到贵方服务端,由贵方服务端通过[getConfig接口](https://support.dun.163.com/documents/761315885761396736?docId=771983453572567040)转发给易盾服务端,由易盾服务端响应
        // 易盾服务端返回结果,再将结果通过 通用查询接口(Cmd_SetConfigData) 反馈给反外挂sdk
        // char *config_buf = nullptr;
        // size_t config_buf_size = 0;
        // htp_ioctl(Cmd_SetConfigData, configData, config_buf, &config_buf_size); configData为易盾服务端返回的数据
        // SAFEFREE(config_buf)
        return 0;
    }
    

    示例代码

    /**
     * htp防剥离线程,验证反外挂是否已经正常启动,建议在初始化完成之后,立马调用
     * 可简单判断反外挂是否正常启动,接入简单
     */
    void *check_htp_alive_thread(void *arg) {
        sleep(60);
        if (!htp_check_alive()) {
            // 反外挂已被剥离
            LOGD("error htp is not alive");
        } else {
            // 反外挂正常
            LOGD("htp is alive");
        }
        return nullptr;
    }
    
    void my_htp_init() {
    	GameSetInfo info;
        info.server_type = 1; // 服务器所在地址,1:中国大陆,2:中国台湾地区,3:其他地区,4:欧盟地区
        info.channel = "testchannel"; // 渠道
        info.game_key = "fed80c732b7b467ea2156c29f830eed24fc8"; // 易盾HTP分配gameKey,与手游加固的appKey对应,gameKey可登录易盾后台获取(如果没有调用数据校验(getDataSign)接口,此值可以为空或者不设置)
        std::map<std::string, std::string> ext_data;
        ext_data["c"] = "1";
        ext_data["e"] = "11Y=";
        ext_data["i"] = "222";
        info.ext_data = ext_data; // 额外信息,反作弊接口需要,可不设置
        htp_init(appid, info, htp_init_callback);
        // 初始化结束之后,立马启动htp防剥离线程
        pthread_t t;
        pthread_create(&t, nullptr, check_htp_alive_thread, nullptr);
    }
    

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

    设置用户信息接口(setRoleInfo)

    接口用途:

    游戏类型应用,在进行数据采集的过程中,会将角色 ID,角色名称、用户/角色账号等设置在风控 SDK 采集的数据中一同上传,用于表示角色信息,以便对有恶意、风险行为的用户/角色进行相应的处置。

    接口须知:

    1. 须在 SDK 初始化用户同意隐私政策后才能调用该接口
    2. 凡是涉及到用户登录、或者切换角色的地方,均需要调用该接口设置或者更新用户/玩家信息;

    函数原型:

    int htp_set_role_info(const char *business_id, const char *role_id, const char *role_name, const char *role_account,
                           const char *role_server, int server_id, const char *game_json);
    

    参数说明:

    参数 说明 必要性
    business_id 当前业务 ID 必填
    role_id 用户/玩家的角色 ID 必填
    role_name 用户/玩家的角色名称 可选,不需要可填null
    role_account 用户/玩家的账号必填 必填
    role_server 用户/玩家的角色的服务器名称 可选,不需要可填null
    server_id 用户/玩家的角色所属服务器的 ID 可选,不需要请传入-1
    game_json 游戏类型应用需要上传的信息,对应一个 json 字符串 可选,不需要可填null

    game_json字段说明:

    key 名称 key 类型 key 值 必要性 说明
    游戏版本号 String GameVersion 可选,不需要可填null 游戏版本号
    资源文件版本 String AssetVersion 可选,不需要可填null 游戏类型应用的资源文件版本号

    示例代码:

    htp_set_role_info(HTP_BUSINESS_ID, "123456","易小盾","yd@163.com", "游戏测试服",1,"");
    

    登出接口(logOut)

    接口用途:

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

    接入须知:

    1. 须在 设置用户信息接口接口被调用后方可调用,在用户/玩家退出当前角色(包括切换角色)或者退出游戏时调用接口。
    2. 此接口主要用于判断用户/玩家本次生命周期,不强制要求接入。
    3. 如果未调用初始化,此接口默认为空,不会执行任何逻辑。

    函数原型:

    void htp_logout();
    

    示例代码:

    htp_logout();   
    

    同步获取凭证(getToken)

    接口用途:

    用于关键业务节点风险防控场景中,比如注册、登录、领券、抽卡、兑换、点赞、评论等业务场景。业务方可通过此接口,获取检测唯一凭证 token。业务服务端通过此凭证实时获取当前用户/玩家风险检测结果,并根据结果进行处置。

    接口适用场景为:
    1、游戏类应用,当 SDK 数据上报接口被屏蔽导致数据上报失败时,通过 getToken 接口获取 SDK 采集信息,并由客户服务端传递给易盾服务器;
    2、全类型应用,在关键业务节点主动调用检测时,通过 getToken 接口获取检测凭证,由客户服务端通过 token 凭证从易盾服务器查询检测结果。
    

    接入须知:

    1. 须在 SDK 初始化且用户同意隐私政策后才能调用该接口,网易易盾隐私说明
    2. 内部存在网络请求,只允许在子线程上调用
    3. 返回值token的使用方法请参考“后端接入-智能风控数据服务接口-在线检测接口”。

    函数原型:

    int htp_get_anti_cheat_token(const char *businessId, char **out, size_t *out_len);
    

    参数说明:

    参数 说明 必要性
    businessId 业务 ID 必填,由易盾后台分配,并在官网“服务管理”中查询
    out token的值 出参,token
    out_len token的长度 出参,token的长度

    返回值:

    说明
    200 成功,当out不再使用时,需手动释放内存
    -201 未初始化
    -203 businessId不合法
    -204 生成token出错
    -205 参数错误,比如 out 或 out_len指针为NULL

    示例代码

    /*
     * 反作弊getToken线程
     */
    void *anti_cheat_token_thread(void *arg) {
        char *token = nullptr;
        size_t token_len = 0;
        int ret = get_anti_cheat_token(appid, &token, &token_len);
        LOGD("ret = %d", ret);
        LOGD("token = %s", token);
        return nullptr;
    }
    
    void start_get_token() {
        pthread_t t;
        pthread_create(&t, nullptr, anti_cheat_token_thread, nullptr);
    }
    

    交互接口(ioctl)

    接口用途:

    1. 用于在客户端查询 SDK 采集的基础数据、设置需要传递给 SDK 数据(比如初始化配置内容、check 结果信息等)、及其他可能的定制功能服务。
    2. 如果未调用初始化,此接口默认返回 -201

    接入须知:

    接口调用前置条件是:调用了设置用户信息接口,并且设置了roleId等信息。

    函数原型:

    int htp_ioctl(int request, const char *data, /*[out]*/char **buf, /*[out]*/size_t *buf_size);
    

    参数说明:

    参数 说明
    request 对应向风控系统请求的命令
    data 设置信息的附加数据
    buf 返回数据buffer
    buf_size 实际使用的buffuer大小

    request值说明:

    enum RequestCmdID
    {
        //初始化配置内容,防止初始化失败情况下,客户可以通过服务端请求初始化配置并传递给SDK
        Cmd_SetConfigData = 16,
        
        //客户服务端将check结果传递给SDK,便于执行后续动作
        Cmd_SetResponseData = 17
    };
    

    返回值:

    错误的情况下,返回:unsupported request(不支持的命令);正确的情况下,返回对应命令的结果。

    注意:该接口的返回值类型均为String,对返回值做判断的时候需要注意该值的类型。

    不同命令设置方法:

    (1) 设置配置信息

    向风控 SDK 配置传递从易盾服务器获取到的产品的配置信息(主要适用于风控 SDK 因被黑灰产屏蔽或其他原因导致无法正常获取配置信息的情况)。

    配置信息

    初始化接口需设置callback

    如果callback的code返回400,将msg发送到服务端,再发送到易盾服务端

    易盾服务端的返回结果即为配置信息

    示例代码:

    char *config_buf = nullptr;
    size_t config_buf_size = 0;
    htp_ioctl(Cmd_SetConfigData, responseData, config_buf, &config_buf_size); responseData为易盾服务端返回的数据
    SAFEFREE(config_buf);
    //如果入参为null或空,则表示查询当前内存中配置版本;如果参数不为空,则表示更新初始化配置
    

    返回值: 返回值为一个json:

    {"s":0,"v":33554433}//s:状态,int类型,只有为0,v 字段的值才有意义;
                       // v:版本,long类型(8字节),配置的版本
    
    返回值 说明
    s 0:成功 -1:内存配置加载失败
    v 配置的版本号
    (2) 设置响应信息

    向风控 SDK 配置传递从易盾服务端获取到的命中及响应结果信息,以便 SDK 执行相关处置动作(主要适用于风控 SDK 因被黑灰产屏蔽或其他原因导致无法正常获取响应结果的情况)。

    响应结果信息

    调用获取凭证(getToken)接口,获取token

    token发送到服务端,在服务端调用check接口,获取结果,其中的 sdkRespData 即为 响应结果信息。

    示例代码:

    char *data1 = nullptr;
    size_t data1_size = 0;
    htp_ioctl(Cmd_SetResponseData, response, &data, &data1_size);
    SAFEFREE(data)
    SAFEFREE(data1)
    

    返回值: 返回值为字符串格式:

    返回值 说明
    0或者-1 输入数据格式有误
    1 解析成功

    安全通信协议接口

    接口用途:

    该接口用于对通信数据进行白盒加密和白盒 HMAC 签名,加密和签名的密钥均会被隐藏,攻击者无法获取,从而保障应用/游戏的通信安全。

    最新版本接口(V2.1)更新内容如下:

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

    接口须知:

    如需使用该接口,请联系易盾获取详细说明文档。

    本地数据加解密接口

    接口用途:

    该接口用于对应用/游戏本地存储的数据进行加解密,保护本地数据安全(游戏类型应用可用于本地游戏存档保护)

    接口须知:

    1. 加密后的数据,需要接入方自行存储,风控 SDK 只提供加密和解密功能。
    2. 初始化接口的配置类必须设置gameKey
    3. 只有返回1,才表示调用成功

    函数原型:

    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签名绑定

    返回值:

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

    模拟点击AI识别

    接口用途:

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

    接入须知:

    SDK5.3.5以之后版本支持该接口

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

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

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

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

    (2)关闭数据采集

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

    取消点击事件数据采集。

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