YSDK_防沉迷能力接入说明

目录


一、 接入 配置

1、 使用防沉迷功能必须先接入 YSDK 1.5.13 及以上版本。
2、 在 工 程 的 assets 文 件 下 的 ysdkconfig.ini 配 置 文 件 中 添 加YSDK_ANTIADDICTION_SWITCH=true,可参考 ysdkdemo 中 ysdkconfig.ini 文件中的配置。如果没有添加该配置或者 YSDK_ANTIADDICTION_SWITCH=false,将不会开启防沉迷功能。
3、 具体接入流程可参考本接入文档第四部分【接入示例】。
4、 需要注意,一定要在沙箱环境(ysdktest.qq.com)中测试完成后,再切到线上环境。

二、 防沉迷流程

防沉迷主要分为三部分功能:1、用户实名认证;2、未成年时长防沉迷;3、未成年支付限制
1、 实名认证
用户实名认证检测时机在用户登录游戏时进行,游戏调用 YSDK 的登录能力,YSDK检测到用户(openid 纬度)未进行实名认证,会弹窗提示用户进行实名认证流程,因为实名认证流程会中断登录流程,YSDK 会在 UserListener.OnLoginNotify 回调中返回用户登 录 失 败 , 失 败 原 因 的 错 误 码 为 3103 , 游 戏 可 根 据 UserLoginRet.flag=eFlag.Login_NeedRegisterRealName 来判断是否是由于需要实名认证导致的登录失败。
用户实名认证成功或者失败的结果不会回调给游戏方(用户在实名认证弹窗内可以看到实名认证结果),用户关闭实名认证弹窗后,需要重新点击游戏登录进入游戏,如果实名认证成功,用户可以正常登录进入游戏,如果实名认证失败,会继续唤起实名认证弹窗,进行实名认证。所以游戏在收到3103的错误码时,可以弹一个toast提示用户,需要完成实名认证,在收到实名认证弹窗关闭的回调时,需要重新调起登录界面。

2、 时长防沉迷
游戏方需要调用 YSDKApi.setAntiAddictGameStart()设置游戏开始计时,调用YSDKApi. setAntiAddictGameEnd()设置游戏结束计时,YSDK 后台会统计用户(openid纬 度 ) 的 游 戏 时 长 , 如 果 累 计 时 长 超 过 防 沉 迷 规 定 , 会 回 调AntiAddictListener.onTimeLimitNotify(AntiAddictRet ret)方法。

3、 登录防沉迷限制
用户在登录后,YSDK 会校验一次用户的防沉迷状态(时长达到当日上限、宵禁等),如 果 检 测 到 用 户 有 防 沉 迷 限 制 , 会 回 调 AntiAddictListener.onLoginLimitNotify(AntiAddictRet ret)方法。

4、 支付限制
使用 YSDK 支付能力的游戏,未成年支付限制由 YSDK 统一处理,游戏方不需要额外开发。用户如果达到了防沉迷充值限制,在进行充值行为时,会弹窗提醒用户无法充值。游戏方会收到支付失败的回调,PayListener.OnPayNotify(PayRet ret)的回调中, PayRet.flag 会返回 1138 的错误码。(1138 错误码是一个大类,游戏方不要根据该错误码判断是否是防沉迷的充值限制。)

三、 接口说明

1、AntiAddictListener

/**
* 防沉迷监听
*/
public interface AntiAddictListener {
// 登录限制的防沉迷回调
void onLoginLimitNotify(AntiAddictRet ret);
// 时长限制的防沉迷回调
void onTimeLimitNotify(AntiAddictRet ret);
}

(1)onLoginLimitNotify 回调时机:用户登录后,会校验一次用户的防沉迷状态,如果检测到用户需要进行防沉迷限制,会回调 onLoginLimitNotify。
(2)onTimeLimitNotify 回调时机:游戏方调用游戏开始和结束时,会校验一次用户的防沉迷状态,如果检测到用户需要进行防沉迷限制,会回调 onTimeLimitNotify;游戏时长计时中,每隔一定时间,会去校验一次用户的防沉迷状态,如果检测到用户需要进行防沉迷限制,会回调 onLoginLimitNotify。
(3)AntiAddictRet:防沉迷指令
表格分类格式:

字段 类型 说明
type Int 指令类型(见下方指令类型)
title String 弹窗标题(type=1 或 2 时有效)
content String 弹窗内容(type=1 或 2 时有效)
url String 打开的网址(type=3 时有效
modal Int 1 表示关闭弹窗需要退出登录;默认为 0,允许关闭弹窗
ruleFamily String 命中的防沉迷规则名称


指令类型(type)

类型 说明
TYPE_UNDEFINED 0 未定义,不需要处理
TYPE_TIPS 1 弹提示
TYPE_LOGOUT 2 强制下线
TYPE_OPEN_URL 3 打开网页窗口


防沉迷规则(ruleFamily)

类型 说明
RULE_HOLIDAY_TIP xg_holiday_tip 节假日 2 小时提醒
RULE_HOLIDAY_NO_PLAY xg_holiday_noplay 节假日 3 小时禁玩
RULE_WORK_TIP xg_work_tip 工作日 1 小时提醒
RULE_WORK_NO_PLAY xg_work_noplay 工作日 1.5 小时禁玩
RULE_NIGHT_NO_PLAY xg_alltime_noplaytime 所有时间宵禁



指令类型(type)的详细说明
(1) 弹提示(type = 1)
在游戏内弹出弹框(弹框由游戏进行实现,弹窗类型无要求),进行用户文案提示(返回的 title 为标题,msg 为显示框内容),用户点击弹窗内的确定按钮后,可正常进行游戏。弹窗内文案由健康系统下发,游戏直接在游戏内进行显示。
(2) 强制下线(type = 2)
在游戏内弹出弹框(弹框由游戏进行实现,弹窗类型无要求),进行用户文案提示(返回的 title 为标题,msg 为显示框内容),用户点击弹窗内的确定按钮后,退出游戏,无法进行游戏。弹窗内文案由健康系统下发,游戏直接在游戏内进行显示。
(3) 打开网页窗口(type=3)
在游戏内打开健康系统下发的一个 URL。打开时机,可在对局结束之后。该指令为防沉迷中控预埋能力,游戏方需要实现一个可关闭的 webview 弹窗,加载指令中下发的 url,具体交互根据 modal 字段来判断(可参考 ysdkdemo 中的示例)。目前测试环境暂无此指令,如需测试,可在下发 1、2 指令的时机,手动添加一个 url,去唤起游戏方的 webview 弹窗测试。

2、 YSDKApi.setAntiAddictListener(AntiAddictListener listener)

设置全局防沉迷监听

3、 YSDKApi. setAntiAddictGameStart()

设置游戏开始计时(注意,如果应用不在前台,调用此接口不会启动游戏计时)

4、 YSDKApi. setAntiAddictGameEnd()

设置游戏结束计时

5、 YSDKApi.reportAntiAddictExecute(AntiAddictRet ret, long executeTime)

游戏方执行完防沉迷指令后,需要调用该接口,该接口用于上报指令执行情况。ret为指令信息,executeTime 为指令执行的时间(毫秒)。

6、 YSDKApi. setAntiAddictLogEnable(boolean enable)

游戏方在调试阶段,可以设置打开防沉迷的日志输出,方便调试,但注意正式上线时要将该日志关闭。其中,返回数据中 duration 为已游戏的时长,单位为秒,时长统计以 5 分钟步长统计,该数据每 5 分钟会返回一次。
YDKDfangchenminenglijierushuoming-001.png

7、 YSDKApi.setAntiRegisterWindowCloseListener(AntiRegisterWindowCloseListener listener)

游戏方如果需要监听实名认证弹窗的关闭时机,可以设置此 listener。(该回调只监听实名认证弹窗关闭时机,不会返回实名认证结果)。

四、 接入 示例

Step1. 在 工 程 的 assets 文 件 下 的 ysdkconfig.ini 配 置 文 件 中 添 加YSDK_ANTIADDICTION_SWITCH=true
YDKDfangchenminenglijierushuoming-002.png

Step2. 处理登录回调中收到的需要进行实名认证的错误码(此处仅为 Demo 样例,具体交互由游戏方自行实现
YDKDfangchenminenglijierushuoming-003.png

Step3. 实现 AntiAddictListener 接口(可参考 YSDKDemo 中的 YSDKCallback 类,此处仅为 Demo 样例,具体弹窗样式和交互由游戏方自行实现
游戏方通过实现 AntiAddictListener 接口,可以监听用户是否需要进行防沉迷限制,在收到防沉迷指令后,游戏方可自行决定防沉迷指令的执行时机。
注意:
(1)在游戏方执行完防沉迷指令后,需要调用 YSDKApi. reportAntiAddictExecute()接口上报指令完成信息。
(2)游戏可能会收到连续的防沉迷指令,游戏方需要处理互斥,避免出现连续弹窗,影响用户体验。
YDKDfangchenminenglijierushuoming-004.png

YDKDfangchenminenglijierushuoming-005.png

Step4. 设置全局的防沉迷监听
调用 YSDKApi.setAntiAddictListener()接口设置全局的防沉迷监听,初始化时机可在 YSDK 初始化之后。
YDKDfangchenminenglijierushuoming-006.png

Step5. 设置游戏开始计时和结束计时,用于统计用户游戏时长
游戏时长统计的开始时间和结束时间由游戏方调用 YSDKApi. setAntiAddictGameStart()和 YSDKApi. setAntiAddictGameEnd()来控制。游戏方自行决定游戏时长开始计时和结束计时的时机。
注意:
(1)、因为游戏时长的统计是基于用户的 openid 纬度,所以游戏开始和结束设置必须在用户登录之后;
(2)、用户登出(logout)后,时长统计会自动停止,游戏方无需处理;
(3)、应用不在前台时(切后台、锁屏等),时长统计会自动停止,游戏方无需处理;
(4)、时长统计有超时逻辑,如果应用异常退出或者杀掉进程,如果超过一定时间后台未收到客户端上报的心跳请求,后台会停止计时,并且游戏时间会恢复到最后一次有心跳上报的统计计时。

五、 防沉迷 D Do emo 样例 (此处仅为样例展示,具体文案和 样式 以线上为准)

1、实名认证(YSDK 已有功能,只需要游戏方添加相应配置即可)

(1)、实名认证弹窗
YDKDfangchenminenglijierushuoming-007.png

(2)、实名认证成功
YDKDfangchenminenglijierushuoming-008.png

(3)、实名认证失败

YDKDfangchenminenglijierushuoming-009.png

2、防沉迷限制(指令由 YSDK 下发,弹窗样式和交互需要游戏方自行实现,此处仅为 YSDKDemo 样例展示)

(1)、弹窗提醒
YDKDfangchenminenglijierushuoming-010.png

(2)、强制下线(游戏时长达到上限)
YDKDfangchenminenglijierushuoming-011.png

(3)、强制下线(宵禁)
YDKDfangchenminenglijierushuoming-012.png

3、支付限制(YSDK 已有功能,游戏方不需要实现)

用户如果达到了防沉迷充值限制,在进行充值支付行为之后,如果后台检测到用户有防沉迷限制,会返回弹窗提醒用户无法充值。目前支付限制在沙箱环境可以测试,正式环境要到 5月底上线。
YDKDfangchenminenglijierushuoming-013.png

以上信息是否解决您的问题?

Copyright © 1998 - 2020 Tencent. All Rights Reserved.

腾讯公司 版权所有

返回顶部