智能风控 uni-app 接入文档

2024.05.08 14:16:41

    隐私说明

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

    接入说明

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

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

    注意:

    接入步骤

    导入插件

    将插件文件夹粘贴到工程根目录的nativeplugins文件夹中。导入插件之后一定要自定义基座方可生效,自定义基座说明请参考 https://uniapp.dcloud.net.cn/tutorial/run/run-app.html#customplayground

    SDK接口调用

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

    (1)初始化

    插件声明

    const htp = uni.requireNativePlugin("htpplugin");
    

    初始化接口

    htp.init({
    	productId: 'XXXXXXX', // 产品id
    	serverType: 1 ,			// 
    	channel: 'testchannel', // 渠道名称
    }, e => {
    	// 回调函数
    	uni.showToast({
    		title: '响应数据:' + JSON.stringify(e),
    		icon: 'none'
    	});
    })
    

    (2)登录接口

    用户登录或者切换游戏账号的时候,调用以下接口

    let json = {GameVersion: 'testGameVersion', AssetVersion: 'testAssetVersion'};
    let stringJson = JSON.stringify(json);
    htp.setRoleInfo({
    	businessId: 'xxxxxxxxxxxxxxxxxxxxx',
    	roleId: 'testroleId' ,
    	roleName: 'testroleName' ,
    	roleAccount: 'testroleAccount' ,
    	roleServer: 'testroleServer' ,
    	serverId: 1 ,
    	gameJson: stringJson ,
    }, e => {
    	// 回调函数
    	uni.showToast({
    		title: '响应数据:' + JSON.stringify(e),
    		icon: 'none'
    	});
    })
    

    验证SDK接入是否正确

    1、确认客户端SDK相关接口已调用

    2、运行程序,确保已触发相关接口。

    3、前往官网查询数据;输入角色信息进行查询

    SDK 接入调用说明

    SDK 初始化接口

    接口用途:

    用于初始化智能风控 SDK。

    接入须知:

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

    函数原型:

    init( String productId,
          int serverType,
          String channel)
    

    参数说明:

    • 入参说明:

      参数 说明 必要性
      productId 易盾HTP分配的productId,可登录易盾后台获取 必填
      serverType 设置服务器归属地 ,智能风控默认上报的服务器为中国大陆的服务器,若需要更改服务器归属地,可以调用该接口进行配置,支持的类型如下:
      serverType = 1,中国大陆地区,默认为该值,无需设置
      serverType = 2, 中国台湾地区 ;
      serverType = 3 海外地区
      可选
      channel 设置渠道信息,供用户传入该app的渠道信息(比如:App Store CN/App Store EU) 可选
    • 回调参数说明:

      回调参数 类型 描述
      code int 初始化结果code码
      200:成功
      199:初始化参数错误,如productId不合法或者过期
      400:请将 msg 发送到贵方服务端,由贵方服务端通过[getConfig接口配置下发接口](https://support.dun.163.com/documents/761315885761396736?docId=771983453572567040)转发给易盾服务端,由易盾服务端响应
      msg String 初始化结果详情

    示例代码:

    htp.init({
    	productId: 'XXXXXXX', // 产品id
    	serverType: 1 ,			// 服务器归属地
    	channel: 'testchannel', // 渠道名称
    }, e => {
    	// 回调函数
    	uni.showToast({
    		title: '响应数据:' + JSON.stringify(e),
    		icon: 'none'
    	});
    })
    

    设置用户信息接口

    接口用途:

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

    接口须知:

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

    函数原型:

    setRoleInfo(
          String businessId,
          String roleId,
          String roleName,
          String roleAccount,
          String roleServer,
          int serverId,
          String gameJson)
    

    参数说明:

    参数 说明 必要性
    businessId 当前业务 ID 必填
    roleId 用户/玩家的角色 ID;非游戏类型应用,roleId 可以与 roleAccount 相同 必填
    roleName 用户/玩家的角色名称;非游戏类型应用,roleName 可以是当前用户昵称相同 可选,不需要可填null
    roleAccount 用户/玩家的账号;如业务方同时接入易盾反垃圾,则此账号需要与反垃圾接入中的account一致 可选,不需要可填null
    roleServer 用户/玩家的角色的服务器名称 可选,不需要可填null
    serverId 用户/玩家的角色所属服务器的 ID 可选,不需要可填null
    gameJson 游戏类型应用需要上传的信息,对应一个 json 字符串 可选,不需要可填null

    gameJson 字段说明:

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

    示例代码:

    let json = {GameVersion: 'testGameVersion', AssetVersion: 'testAssetVersion'};
    let stringJson = JSON.stringify(json);
    htp.setRoleInfo({
    	businessId: 'xxxxxxxxxxxxxxxxxxxxx',
    	roleId: 'testroleId' ,
    	roleName: 'testroleName' ,
    	roleAccount: 'testroleAccount' ,
    	roleServer: 'testroleServer' ,
    	serverId: 1 ,
    	gameJson: stringJson ,
    }, e => {
    	// 回调函数
    	uni.showToast({
    		title: '响应数据:' + JSON.stringify(e),
    		icon: 'none'
    	});
    })
    

    函数返回:

    • 注:iOS没有回调值

    • 回调参数说明:

      回调参数 类型 描述
      code int 0:成功
      201:未初始化
      203:businessId 不合法

    登出接口

    接口用途:

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

    接入须知:

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

    函数原型:

    logOut()
    

    示例代码:

    Future<void> logOut()
    

    同步获取凭证

    接口用途:

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

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

    接入须知:

    1. 需要在 SDK 初始化且用户同意隐私政策后才能调用该接口,网易易盾隐私说明
    2. 该函数内部会进行网络请求。

    函数原型:

    getToken(int timeout, String businessId)
    

    参数说明:

    • 入参说明:

      参数 说明 必要性
      businessId 业务 ID 必填,由易盾后台分配,并在官网“服务管理”中查询
      timeout 函数超时时间 必填,单位毫秒,[1000,10000],此区间外的默认为300
    • 返回值说明:

      返回字符串格式的JSON

      返回值 类型 说明
      code int 结果码,不同结果码含义如下:200:表示调用成功,其他结果码均表示调用失败;201:SDK未初始化;202:在主线程运行;203:businessId不合法;204:其他情况
      codeStr string 结果码对应的字符说明,200:success;201:error. not init;202:error. run on main thread;203:businessId invalid;204:gen token error
      token string 当 code 为200时,返回正常token。当网络状态不佳或者超时时,会返回离线 token
      businessId string 由易盾后台分配,并在官网“服务管理”中查询
    • 示例代码:

    var result = htp.getToken({timeout: 1000,businessId: 'ab51b8dbadb6894192eeeaafd6973d0e',});
    

    异步获取凭证

    接口用途:

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

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

    接入须知:

    1. 需要在 SDK 初始化且用户同意隐私政策后才能调用该接口,网易易盾隐私说明
    2. 该函数内部会进行网络请求。

    函数原型:

    getTokenAsync(int timeout, String businessId)
    

    参数说明:

    • 入参说明:

      参数 说明 必要性
      businessId 业务 ID 必填,由易盾后台分配,并在官网“服务管理”中查询
      timeout 函数超时时间 必填,单位毫秒,[1000,10000],此区间外的默认为300
    • 回调参数说明:

      回调参数 类型 说明
      code int 结果码,不同结果码含义如下:200:表示调用成功,其他结果码均表示调用失败;201:SDK未初始化;202:在主线程运行;203:businessId不合法;204:其他情况
      codeStr string 结果码对应的字符说明,200:success;201:error. not init;202:error. run on main thread;203:businessId invalid;204:gen token error
      token string 当 code 为200时,返回正常token。当网络状态不佳或者超时时,会返回离线 token
      businessId string 由易盾后台分配,并在官网“服务管理”中查询

    示例代码:

    htp.getTokenAsync({
    	timeout: 1000,
    	businessId: 'ab51b8dbadb6894192eeeaafd6973d0e',
    }, e => {
    	// 回调函数
    	uni.showToast({
    		title: '响应数据:' + JSON.stringify(e),
    		icon: 'none'
    	});
    })
    

    交互接口(ioctl)

    接口用途:

    用于在客户端查询 SDK 采集的基础数据、设置需要传递给 SDK 数据(比如初始化配置内容、check 结果信息等)、及其他可能的定制功能服务。

    接入须知:

    接口调用前置条件是:调用了初始化接口并且同意隐私政策之后。

    函数原型:

    ioctl(int request, String data)
    

    参数说明:

    • 入参说明:

      参数 说明 必要性
      request 16:初始化配置内容,防止初始化失败情况下,客户可以通过服务端请求初始化配置并传递给SDK
      17:客户服务端将check结果传递给SDK,便于执行后续动作
      20:获取服务端设备指纹
      必填
      data 设置信息的附加数据
      入参为16或者17时,要将根据类型设置对应数据
      可选,不需要可填""
    • 回调参数说明:

      回调参数 类型 描述
      msg String 入参 request = 16,返回值为字符串格式的JSON {"s":0,"v":33554433}
      //s:状态,int类型,只有为0,v 字段的值才有意义;
      // v:版本,long类型(8字节),配置的版本
      入参 request = 17,返回值为字符串格式: 0或者-1,输入数据格式有误;1为解析成功
      入参 request = 20,返回值为字符串格式:-1,SDK未初始化;2001,无服务端设备指纹缓存;2002,设备指纹服务端获取失败;2003,设备指纹服务端校验失败;2004,设备指纹本地获取失败;2005,设备指纹本地校验失败
    Online Chat Tel:95163223 Free trial