智能风控 iOS 端接入文档(OC)

2024.11.25 17:57:08

    隐私说明

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

    接入说明

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

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

    应用必须接入:

    游戏必须接入:

    建议接入:

    接入步骤

    请登陆易盾官网后台风控引擎-服务管理获取sdk,详情如图。image title 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.frameworkCoreTelephony.frameworkSystemConfiguration.frameworklibc++.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

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

    image title

    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 凭证从易盾服务器查询检测结果。
    

    接入须知:

    • 须在 SDK 初始化且用户同意隐私政策后才能调用该接口,网易易盾隐私说明

    • 内部存在网络请求,只允许在子线程上调用

    • 返回值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)

    接口用途:

    同步获取凭证

    接入须知:

    • 须在 SDK 初始化且用户同意隐私政策后才能调用该接口,网易易盾隐私说明

    • 在主线程调用,回调也在主线程。

    • 返回值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等信息后调用。

    接口须知:

    请在作弊情况较严重的玩法和场景下调用registerTouchEventunregisterTouchEvent,开启和关闭点击数据的采集,初次接入建议设置一个玩法和场景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];
    
    Online Chat Tel:95163223 Free trial