Endpoints屏幕使用时间

提交会话已完成的屏幕使用时段

为某个 k-ID 会话提交一个或多个已完成的屏幕使用时段。每个事件记录一段使用何时开始、持续多久。当使用情况只能事后得知时使用本接口——例如先缓存时段再定期上传的后端,或在关闭时上报会话总量的游戏引擎。 每个被接受的时段会将其 `durationSeconds` 计入玩家当天的屏幕使用总量。若某个时段在家长设定的时区内跨越午夜,则会拆分到两个日期,使每天的总量都反映当天实际发生的使用。 各事件独立处理。响应中包含每个事件的状态: * `accepted` - 时段已记录并计入当天总量。重复提交 `id` 已被接受的事件是安全的空操作:它会再次计为 `accepted`,不会被重复计入,因此网络故障后的重试不会重复累计。 * `rejected` - 时段未通过校验;`reason` 指明违反了哪条规则。 若会话不存在或已被撤销,则整批请求被拒绝。 实时限制信号(`Screentime.LimitWarning`、`Screentime.LimitReached`、`Screentime.BreakReminder`)不会由本接口触发。若集成需要在越过阈值的那一刻触发这些 webhook,请使用 `/screentime/start` 与 `/screentime/end`。

POST
/screentime/push
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/screentime/push" \  -H "Content-Type: application/json" \  -d '{    "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672",    "events": [      {        "id": "9d4e2f81-7a3b-4c56-8e90-1f2a3b4c5d6e",        "durationSeconds": 1800,        "timestamp": "2026-06-24T09:00:00Z"      },      {        "id": "c1b2a3d4-5e6f-4708-9a1b-2c3d4e5f6071",        "durationSeconds": 2400,        "timestamp": "2026-06-24T13:00:00Z"      }    ]  }'
{  "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672",  "accepted": 2,  "rejected": 0,  "events": [    {      "id": "9d4e2f81-7a3b-4c56-8e90-1f2a3b4c5d6e",      "status": "accepted"    },    {      "id": "c1b2a3d4-5e6f-4708-9a1b-2c3d4e5f6071",      "status": "accepted"    }  ]}