# 防沉迷-对外服务接口

域名联系何世玮获取
请求均需使用https范围
非特殊说明情况下，均使用GET

# 1、账号游戏内角色上线

# 请求路径

https://域名/useronline

# 功能说明

该接口访问需要鉴权，具体参见"附录"->"其他 SDO 服务端"->"SDO API访问鉴权"
所有账号上线必须调用该接口告知防沉迷服务，由防沉迷服务同步给中宣部
针对成年人调用该接口需要有机制尽可能保证该接口调用成功，建议调用失败的情况下隔一分钟后重试，重试3次均失败时不再重试

# 请求参数

字段名	类型	必填	说明
appid	int	Y	应用编码，必须使用实际的游戏appid
areaid	int	Y	应用区号
groupid	int	Y	应用组号
userid	string	Y	账号id
accounttype	int	Y	userid传入的账号类型：0=数字账号、1=pt账号、2=个性账号、3=手机帐号、4=邮箱帐号、25=手游appmid
characterid	string	Y	角色
deviceid	string	N	玩家设备号
endpointip	string	Y	客户端ip
endpointport	string	Y	客户端port
guid	string	Y	消息追踪id，由调用方生成，用于问题排查
eventtime	string	Y	上线时间，注不能是请求时间，格式：yyyy-mm-dd hh24:mi:ss

# 业务响应

{"return_code": 0,"return_message": "","data": {下述表格描述此处字段}}

字段名	类型	说明
appId	int	应用编码
areaId	int	应用区号
groupId	int	应用组号
userId	string	账号id
onlineTimeVal	int	当天累积在线时长，单位秒
remainingTime	int	当天剩余可玩时长，单位秒
msg	string	提示信息，当该字段有值时，可用于客户端展示

示例

{
    "return_code": 0,
    "error_type": 0,
    "return_message": "",
    "data": {
        "appId": 791000306,
        "areaId": 3,
        "groupId": 30146,
        "msg": "",
        "onlineTimeVal": 0,
        "remainingTime": 2147483647,
        "resultCode": 0,
        "userId": "2789599212"
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 业务错误

错误码	错误描述	详细说明

# 2、账号游戏内角色下线

# 请求路径

https://域名/useroffline

# 功能说明

该接口访问需要鉴权，具体参见"附录"->"其他 SDO 服务端"->"SDO API访问鉴权"
所有账号下线必须调用该接口告知防沉迷服务，由防沉迷服务同步给中宣部
针对成年人调用该接口需要有机制尽可能保证该接口调用成功，建议调用失败的情况下隔一分钟后重试，重试3次均失败时不再重试

# 请求参数

字段名	类型	必填	说明
appid	int	Y	应用编码，必须使用实际的游戏appid
areaid	int	Y	应用区号
groupid	int	Y	应用组号
userid	string	Y	账号id
accounttype	int	Y	userid传入的账号类型：0=数字账号、1=pt账号、2=个性账号、3=手机帐号、4=邮箱帐号、25=手游appmid
characterid	string	Y	角色
deviceid	string	N	玩家设备号
endpointip	string	Y	客户端ip
endpointport	string	Y	客户端port
guid	string	Y	消息追踪id，由调用方生成，用于问题排查
eventtime	string	Y	上线时间，注不能是请求时间，格式：yyyy-mm-dd hh24:mi:ss

# 业务响应

{"return_code": 0,"return_message": "","data": {下述表格描述此处字段}}

字段名	类型	说明
appId	int	应用编码
areaId	int	应用区号
groupId	int	应用组号
userId	string	账号id
onlineTimeVal	int	当天累积在线时长，单位秒
remainingTime	int	当天剩余可玩时长，单位秒

示例

{
    "return_code": 0,
    "error_type": 0,
    "return_message": "",
    "data": {
        "appId": 791000306,
        "areaId": 3,
        "groupId": 30146,
        "onlineTimeVal": 0,
        "remainingTime": 2147483647,
        "resultCode": 0,
        "userId": "2789599212"
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 业务错误

错误码	错误描述	详细说明

# 3、在线账号心跳

# 请求路径

https://域名/heartbeat

# 功能说明

该接口访问需要鉴权，具体参见"附录"->"其他 SDO 服务端"->"SDO API访问鉴权"
心跳请求的间隔时间为1分钟，游戏服务器需要在每个间隔的心跳请求中，将当前在线的未成年人用户信息完整上报，若当前在线的未成年人账号数量，超过了单个请求的账号数量上限，则分多次请求上报
当防沉迷系统连续三次未接收到某用户的心跳信息，防沉迷系统会判定为游戏服务异常，并将该未成年人用户主动置于offline状态，并发起强制下线通知给游戏服务器，若用户仍在线，游戏服务器负责将该用户踢下线
特殊场景：若游戏服务器未成功处理用户下线请求，后续若该用户在未发送online的情况下出现心跳，则防沉迷系统会主动将其置于online状态
注意：该心跳仅作为异常情况下的补救功能，不作为正常情况下的在线判断逻辑，服务正常的情况下，防沉迷系统会以接收到的online/offline信息计算防沉迷时间

# 请求参数

字段名	类型	必填	说明
appid	int	Y	应用编码，必须使用实际的游戏appid
ip	string	Y	游戏服务器ip
usersinfo	string	N	上报的在线账号信息组，格式为json数组： [ {在线账号信息}, {在线账号信息}, ... ]

# 在线账号信息

字段名	类型	说明
areaid	int	应用编码
groupid	int	应用编码
userid	string	账号id
accounttype	int	userid传入的账号类型：0=数字账号、1=pt账号、2=个性账号、3=手机帐号、4=邮箱帐号、25=手游appmid
characterid	string	角色

# 业务响应

{"return_code": 0,"return_message": "","data": {下述表格描述此处字段}}

字段名	类型	说明

示例

{
    "return_code": 0,
    "error_type": 0,
    "return_message": "",
    "data": {
    }
}

1
2
3
4
5
6
7

# 业务错误

错误码	错误描述	详细说明

# 4、查询用户在线时长

# 请求路径

https://域名/queryonlineduration

# 功能说明

该接口访问需要鉴权，具体参见"附录"->"其他 SDO 服务端"->"SDO API访问鉴权"
当未成年人用户需要进行长时间耗时的任务及副本时，游戏服务器需要调用该接口主动查询该用户剩余在线时长;当剩余在线时长不足以进行该行为时，应拒绝用户的本次请求，同时由游戏给予玩家合理提示

# 请求参数

字段名	类型	必填	说明
appid	int	Y	应用编码，必须使用实际的游戏appid
areaid	int	Y	应用区号
groupid	int	Y	应用组号
userid	string	Y	账号id
accounttype	int	Y	userid传入的账号类型：0=数字账号、1=pt账号、2=个性账号、3=手机帐号、4=邮箱帐号、25=手游appmid
characterid	string	Y	角色
deviceid	string	N	玩家设备号
endpointip	string	Y	客户端ip
endpointport	string	Y	客户端port

# 业务响应

{"return_code": 0,"return_message": "","data": {下述表格描述此处字段}}

字段名	类型	说明
appId	int	应用编码
areaId	int	应用区号
groupId	int	应用组号
userId	string	账号id
onlineTimeVal	int	当天累积在线时长，单位秒
remainingTime	int	当天剩余可玩时长，单位秒
msg	string	提示信息，当该字段有值时，可用于客户端展示

示例

{
    "return_code": 0,
    "error_type": 0,
    "return_message": "",
    "data": {
        "appId": 791000306,
        "areaId": 3,
        "groupId": 30146,
        "msg": "",
        "onlineTimeVal": 0,
        "remainingTime": 2147483647,
        "resultCode": 0,
        "userId": "2789599212"
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 业务错误

错误码	错误描述	详细说明

← 防沉迷业务介绍防沉迷向外通知协议 →