防沉迷接入文档

1 文档概述

此文档为西瓜SDK的防沉迷接入和介绍文档: 本文介绍如何在服务端接入

2 分步指南

游戏接入西瓜防沉迷:需要游戏服务端支持3个接口:

  1. 开始游戏接口:游戏服务器调用西瓜服务器(可选,接入西瓜时和西瓜约定是否以verify-session时间为准开始防沉迷计时,如果是可以不接入开始游戏接口)
  2. 退出游戏:游戏服务器调用西瓜服务器(必接)
  3. 防沉迷游戏时间到通知游戏接口:西瓜服务器调用游戏服务器(必接:游戏需要提供通知URL给西瓜后台配置)

2.1 开始游戏

说明:玩家开始玩游戏时,游戏服务器通知西瓜,西瓜以该时间作为防沉迷计时。可选是否调用接口,接入西瓜时和西瓜约定好,如果游戏不调用该接口,西瓜将以游戏调用西瓜verify-session时间为准开始计时。

类型 说明
接收方 西瓜SDK服务器
接口类型 HTTP POST Content-Type: application/json;charset=UTF-8
字符集编码 UTF-8
URL account/playgame/{xgAppId}

参数:

参数 类型 说明 必填
type String 接口类型,固定为playgame Y
uid String uid Y
platform String 游戏平台,安卓(a)/IOS(i), 如果两个平台的防沉迷回调地址(通知游戏踢出登录用户)相同,可以不传这个参数 N
ts String 登录时间,西瓜以该时间作为防沉迷计时,秒级,格式YYYYMMDDHHMMSS,如20191128160125对应2019/11/28 16:01:25 Y
sign String 签名,同西瓜签名算法 https://www.xgsdk.com/doc/section3/pay.html 2.7 章节,使用游戏服务端密钥 Y

返回:

参数 类型 说明 必填
code String 返回码,0代表成功,其它错误码请参考错误码章节 Y
msg String 接口调用信息提示,成功为success Y
错误码 备注
0 成功
-1 签名失败
-2 xgAppid不存在
-3 游戏的防沉迷配置出错,需要在西瓜平台检查配置
-4 用户未实名认证,请先完成实名认证
-5 游客1小时体验时间到
-6 同一设备,15天内不得重复体验游客模式
-7 未成年时间到,每日22时到次日8时不提供游戏服务
-8 未成年游戏时间到,法定节假日每日累计不得超过3小时/其他时间每日累计不得超过1.5小时
-99 西瓜SDK服务器内部错误

请求示例:

post url : http://{xgsdk服务器域名}/account/playgame/22320043?type=login&uid=jinshan_uid001&ts=20191128160125&sign=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST Body:
    {
        "type": "playgame",
        "uid": "jinshan__001",
        "ts": "20191128160125",
        "sign": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }

返回样例:

{
    "code": "0",
    "msg": "success"
}

2.2 退出游戏

说明:游戏玩家实际退出游戏时,通知西瓜,西瓜以该时间作为防沉迷终止计时,必调接口。

类型 说明
发起方 游戏服务器
接收方 西瓜SDK服务器
接口类型 HTTP POST Content-Type: application/json;charset=UTF-8
字符集编码 UTF-8
URL account/exitgame/{xgAppId}

参数:

参数 类型 说明 必填
type String 接口类型,固定为exitgame Y
uid String uid Y
platform String 游戏平台,安卓(a)/IOS(i), 如果两个平台的防沉迷回调地址(通知游戏踢出登录用户)相同,可以不传这个参数 N
ts String 登录时间,西瓜以该时间作为防沉迷终止计时,秒级,格式YYYYMMDDHHMMSS,如20191128160125对应2019/11/28 16:01:25 Y
sign String 签名,同西瓜签名算法 https://www.xgsdk.com/doc/section3/pay.html 2.7 章节,使用游戏服务端密钥 Y

返回:

参数 类型 说明 必填
code String 返回码,0代表成功,其它错误码请参考错误码章节 Y
msg String 接口调用信息提示,成功为success Y
错误码 备注
0 成功
-1 签名失败
-2 xgAppId不存在
-3 游戏的防沉迷配置出错,需要在西瓜平台检查配置
-99 西瓜SDK服务器内部错误

请求示例:

post url : http://{xgsdk服务器域名}/account/exitgame/22320043/jinshan_uid001?ts=20191128160125&sign=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST Body:
    {
        "type": "exitgame",
        "uid": "jinshan__001",
        "ts": "20191128160125",
        "sign": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }

返回样例:

{
    "code": "0",
    "msg": "success"
}

2.3 防沉迷游戏时间到

说明:西瓜计时防沉迷时间到时通知游戏,可一次多个uid通知游戏。当需要通知游戏所有未成年游戏时间到时,出于通知效率考虑,不会将所有未成年玩家uid通知游戏,只设置allUnderAgeGameExpired=1,游戏需要根据verify-session返回的ceritification字段记录所有未成年玩家信息供西瓜通知到所有未成年,游戏能登出所有未成年玩家。

类型 说明
发起方 西瓜SDK服务器
接收方 游戏服务器
接口类型 HTTP POST Content-Type: application/json;charset=UTF-8
字符集编码 UTF-8
URL 游戏方提供URL,西瓜SDK服务器主动调用
说明 通知游戏失败时,西瓜不会再补发,请游戏保持接口的稳定性

参数:

参数 类型 说明 必填
type String 接口类型,固定为anti-addiction-game-expired Y
uids String[] 数组,可为空,当有allUnderAgeGameExpired时,uids为空 N
allUnderAgeGameExpired String 有值时,固定传 1: 所有未成年人游戏时间到,可为空,当有uids时,allUnderAgeGameExpired为空 N
ts String 防沉迷游戏时间到时间,秒级,格式YYYYMMDDHHMMSS,如20191128160125对应2019/11/28 16:01:25 Y
sign String 签名,同西瓜签名算法 https://www.xgsdk.com/doc/section3/pay.html 2.7 章节,使用游戏服务端密钥 Y
ext String 扩展字段,备用。正常不传 N

返回:

参数 类型 说明 必填
code String 返回码,0代表成功,其它错误码请参考错误码章节 Y
msg String 接口调用信息提示,成功为success Y
错误码 备注
0 成功
-1 签名失败
1 请求重发,表示游戏服前置机收到xg服务器通知,但是由于游戏服务器正在升级,不能处理响应,请求延后重新发送
-2 xgAppId不存在
-5 账号不存在
-99 服务器内部错误

请求示例:

http://172.63.55.62:18888/anti-addiction/game-expired

POST Body:
    {
        "type": "anti-addiction-game-expired",
        "uids": ["jinshan__001","jinshan__002","jinshan__003"],
        "ts": "20191128160125",
        "sign": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
    或:
    {
        "type": "anti-addiction-game-expired",
        "allUnderAgeGameExpired": "1",
        "ts": "20191128160125",
        "sign": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }

返回样例:

{
    "code": "0",
    "msg": "success"
}

2.5 verify session 错误码

说明:当防沉迷不能登录时,游戏在调用西瓜verify-session接口时会返回下列code,msg错误信息,游戏要根据返回的错误信息自行处理提示不能登录信息给用户。

错误码 备注
-4 用户未实名认证,请先完成实名认证
-5 游客1小时体验时间到
-6 同一设备,15天内不得重复体验游客模式
-7 未成年游戏时间到,每日22时到次日8时不提供游戏服务
-8 未成年游戏时间到,法定节假日每日累计不得超过3小时
-9 未成年游戏时间到,每日累计不得超过1.5小时

2.6 防沉迷不能充值时创建订单返回错误码

说明:当防沉迷不能充值时,游戏可从客户端调用西瓜支付接口时支付失败回调onPayFail的msg字段返回的json值,来提示相关充值失败信息给用户。

msg 为json串:{"code":"-12", "msg":"未满8周岁用户不能充值"}
    {"code":"-13", "msg":"8周岁以上未满16周岁未成年单次充值不得超过50元人民币"}
    {"code":"-14", "msg":"16周岁以上未满18周岁未成年单次充值不得超过100元人民币"}
    {"code":"-15", "msg":"8周岁以上未满16周岁未成年每月充值累计金额不得超过200人民币"}
    {"code":"-16", "msg":"8周岁以上未满16周岁未成年单次充值不得超过50元人民币"}
    {"code":"-17", "msg":"游客不能充值"}

防沉迷不能充值时游戏客户端获取到相关错误信息给玩家弹窗代码示例:

public void onPayFail(PayInfo payInfo, PayResult payResult) {
    String msg=payResult.getMsg();
    try {
        JSONObject jsonObject=new JSONObject(msg);
        String code=jsonObject.getString("code"); //支付失败错误码
        String codeMsg=jsonObject.getString("msg"); //支付失败信息

        if ("-12".equals(code) ||"-13".equals(code) ||"-14".equals(code) ||"-15".equals(code)
            ||"-16".equals(code) ||"-17".equals(code)) {
            //此次游戏可自行决定弹窗提示方式
            ToastUtil.showToastLong(activity, codeMsg);
        }
    } catch (JSONException e) {
      e.printStackTrace();
    }
}
错误码 备注
-12 未满8周岁用户不能充值
-13 8周岁以上未满16周岁未成年单次充值不得超过50元人民币
-14 16周岁以上未满18周岁未成年单次充值不得超过100元人民币
-15 8周岁以上未满16周岁未成年每月充值累计金额不得超过200人民币
-16 16周岁以上未满18周岁未成年每月充值累计金额不得超过400人民币
-17 游客不能充值

2.7 国家政策参考地址

http://www.sapprft.gov.cn/sapprft/contents/6588/407807.shtml