提交会话已完成的屏幕使用时段
为某个 k-ID 会话提交一个或多个已完成的屏幕使用时段。每个事件记录一段使用何时开始、持续多久。当使用情况只能事后得知时使用本接口——例如先缓存时段再定期上传的后端,或在关闭时上报会话总量的游戏引擎。 每个被接受的时段会将其 `durationSeconds` 计入玩家当天的屏幕使用总量。若某个时段在家长设定的时区内跨越午夜,则会拆分到两个日期,使每天的总量都反映当天实际发生的使用。 各事件独立处理。响应中包含每个事件的状态: * `accepted` - 时段已记录并计入当天总量。重复提交 `id` 已被接受的事件是安全的空操作:它会再次计为 `accepted`,不会被重复计入,因此网络故障后的重试不会重复累计。 * `rejected` - 时段未通过校验;`reason` 指明违反了哪条规则。 若会话不存在或已被撤销,则整批请求被拒绝。 实时限制信号(`Screentime.LimitWarning`、`Screentime.LimitReached`、`Screentime.BreakReminder`)不会由本接口触发。若集成需要在越过阈值的那一刻触发这些 webhook,请使用 `/screentime/start` 与 `/screentime/end`。
Authorization
api-key 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" } ]}{ "error": "INVALID_INPUT", "errorMessage": "The request was missing a sessionId parameter."}获取屏幕使用时间状态 GET
返回 `sessionId` 当前的屏幕使用时间状态:家长设定的规则、当天的使用量,以及此刻平台是否可以允许游玩。平台会在会话开始时,以及收到 `Screentime.LimitWarning`、`Screentime.LimitReached`、`Screentime.QuietHoursWarning` 或 `Screentime.QuietHoursReached` webhook 后调用本接口,以刷新自身保存的状态。 当家长尚未为该会话配置屏幕使用时间,或已配置但停用了限制执行时,返回 `{ "enabled": false }`。
申请屏幕使用时间例外 POST
当孩子希望今天多玩一会儿,或希望绕过正在生效的安静时段时,代表孩子提交例外申请。k-ID 会记录该申请并通知家长批准或拒绝。按孩子幂等:若同一个孩子的另一份申请仍在待处理中,此时的调用会原样返回那份待处理申请,而不会创建第二份。 处理结果会以单个 `Screentime.OverrideResult` webhook 异步送达,携带 `status: "granted" | "denied" | "expired"`。webhook 正文在 `state` 下包含与 `GET /screentime/get-state` 相同的结构,因此平台可以直接更新自身保存的状态,无需再次拉取。24 小时内未处理的申请会以 `status: "expired"` 触发 webhook。