GHOME SDK 文档 - 支付中心

# 防沉迷-向外通知接口

为完成《关于防止未成年人沉迷网络游戏工作的通知》相关工作，各游戏需实现接收防沉迷通知消息的服务，用来接收防沉迷系统发来的“用户剩余时长通知”和“强制用户下线通知”；该服务采用http协议或者基于tcp的二进制协议实现，各游戏可根据开发的便利性选择一个实现，但为统一化，防沉迷制定了本页描述的协议接口规范

  • 实现http服务的游戏，url路径自定义，支持按游戏、区、组的层级进行url配置
  • 实现tcp服务的游戏，，支持按游戏、区、组的层级进行ip+port配置

# 一、HTTP协议

# 1、用户剩余时长通知

# 功能说明

  • 接口访问需要鉴权，具体签名算法参见"附录"->"其他 SDO 服务端"->"SDO API访问鉴权"
  • 通知游戏服务端用户剩余时长，游戏根据需要在客户端提醒给用户

# 请求参数

字段名 类型 必填 说明
appid int Y 应用编码，必须使用实际的游戏appid
areaid int Y 应用区号
groupid int Y 应用组号
userid string Y 账号id，与游戏调用online时使用的账号一致
characterid string Y 角色
onlineTimeVal int Y 当天累积在线时长，单位秒
remainingTime int Y 当天剩余可玩时长，单位秒
msg string N 提示信息，当该字段有值时，可用于客户端展示
guid string N 消息追踪id，由调用方生成，用于问题排查

# 业务响应

{
    "return_code": 0,
    "return_message": "",
    "data": { }
}
1
2
3
4
5

返回return_code为0表示通知成功

# 请求示例

请求: https://xxxxx/remain?appid=791000306&areaid=3&characterid=%E5%B0%8F%E9%B1%BC%E4%BA%BA&groupid=3&guid=4b54bbb75d79f1cd0000001788bcd700&merchant_name=test&msg=%E5%89%A9%E4%BD%99%E6%97%B6%E9%97%B4%E4%B8%BA0&onlineTimeVal=2700&remainingTime=900&signature_method=md5&timestamp=1714284578&userid=2627364167&signature=5c0a08944d6af6d16cca9161cb60cdb7
响应：
{
    "return_code": 0,
    "return_message": "",
    "data": { }
}
1
2
3
4
5
6
7

# 2、强制用户下线通知

# 功能说明

  • 接口访问需要鉴权，具体签名算法参见"附录"->"其他 SDO 服务端"->"SDO API访问鉴权"
  • 通知游戏服务端踢未成年人下线
  • 游戏收到强制下线请求时，由游戏处理用户的下线操作，并将操作结果返回给防沉迷系统，强制下线请求接口的msg字段值，需准确显示给用户
  • 收到强制下线请求时，必须立即处理用户下线，不可延迟处理，所以建议当未成年人用户需要进行长时间耗时的任务及副本时，先调用queryonlineduration接口查询剩余游戏时长，确保其剩余时长足够完成任务及副本
  • 当游戏成功处理强制下线操作时，已停止该用户的防沉迷时间累积，无需将该用户的心跳发送至防沉迷系统

# 请求参数

字段名 类型 必填 说明
appid int Y 应用编码，必须使用实际的游戏appid
areaid int Y 应用区号
groupid int Y 应用组号
userid string Y 账号id，与游戏调用online时使用的账号一致
characterid string Y 角色
msg string N 提示信息，当该字段有值时，可用于客户端展示
guid string N 消息追踪id，由调用方生成，用于问题排查

# 业务响应

{
    "return_code": 0,
    "return_message": "",
    "data": { }
}
1
2
3
4
5

返回return_code为0表示通知成功；否则会重发通知， 最多重发3次

# 请求示例

请求: https://xxxxx/kick?appid=791000306&areaid=3&characterid=%E5%B0%8F%E9%B1%BC%E4%BA%BA&groupid=3&guid=4b54bbb75d79f1cd0000001788bcd700&merchant_name=test&msg=%E5%89%A9%E4%BD%99%E6%97%B6%E9%97%B4%E4%B8%BA0&signature_method=md5&timestamp=1714035330&userid=2627364167&signature=b6e2c16b91c9ebc77103dadb7ad85e9d
响应：
{
    "return_code": 0,
    "return_message": "",
    "data": { }
}
1
2
3
4
5
6
7

# 二、基于TCP的二进制协议

# 0、协议说明

||<---包长度(4字节)--->||<---消息类型(4字节)--->||<---消息体(不超2^32-1-4字节)--->||

# 消息结构

项目 说明
Message Header 消息头(所有消息公共包头)
Message Body 消息体

# 消息头格式（Message Header）

字段名 字节数 类型 描述
PackageLength 4 网络字节序4字节整型 消息总长度(含消息头及消息体)
CommandId 4 网络字节序4字节整型 消息类型

# 消息体格式（Message Body）

  • 长度不超不超2^32-1-4字节
  • json格式文本
  • 不同消息体内json定义参见下述各接口的请求参数和业务响应的定义表格

# 1、用户剩余时长通知

# 功能说明

  • 请求包中消息类型值为0x0001
  • 响应包中消息类型值为0x8001
  • 通知游戏服务端用户剩余时长，游戏根据需要在客户端提醒给用户

# 请求参数

字段名 类型 必填 说明
appid int Y 应用编码，必须使用实际的游戏appid
areaid int Y 应用区号
groupid int Y 应用组号
userid string Y 账号id，与游戏调用online时使用的账号一致
characterid string Y 角色
onlineTimeVal int Y 当天累积在线时长，单位秒
remainingTime int Y 当天剩余可玩时长，单位秒
msg string N 提示信息，当该字段有值时，可用于客户端展示
guid string N 消息追踪id，由调用方生成，用于问题排查

# 业务响应

字段名 类型 说明
return_code int 业务处理响应码，实现方自定义
return_message string 业务处理响应描述，实现方自定义
guid string 消息追踪id，使用请求中的值

返回return_code为0表示通知成功

# 2、强制用户下线通知

# 功能说明

  • 请求包中消息类型值为0x0002
  • 响应包中消息类型值为0x8002
  • 通知游戏服务端踢未成年人下线
  • 游戏收到强制下线请求时，由游戏处理用户的下线操作，并将操作结果返回给防沉迷系统，强制下线请求接口的msg字段值，需准确显示给用户
  • 收到强制下线请求时，必须立即处理用户下线，不可延迟处理，所以建议当未成年人用户需要进行长时间耗时的任务及副本时，先调用queryonlineduration接口查询剩余游戏时长，确保其剩余时长足够完成任务及副本
  • 当游戏成功处理强制下线操作时，已停止该用户的防沉迷时间累积，无需将该用户的心跳发送至防沉迷系统

# 请求参数

字段名 类型 必填 说明
appid int Y 应用编码，必须使用实际的游戏appid
areaid int Y 应用区号
groupid int Y 应用组号
userid string Y 账号id，与游戏调用online时使用的账号一致
characterid string Y 角色
msg string N 提示信息，当该字段有值时，可用于客户端展示
guid string N 消息追踪id，由调用方生成，用于问题排查

# 业务响应

字段名 类型 说明
return_code int 业务处理响应码，实现方自定义
return_message string 业务处理响应描述，实现方自定义
guid string 消息追踪id，使用请求中的值

返回return_code为0表示通知成功；否则会重发通知， 最多重发3次

Last Updated: 2024/4/28 07:01:33

←