Endpoints屏幕使用时间

申请屏幕使用时间例外

当孩子希望今天多玩一会儿,或希望绕过正在生效的安静时段时,代表孩子提交例外申请。k-ID 会记录该申请并通知家长批准或拒绝。按孩子幂等:若同一个孩子的另一份申请仍在待处理中,此时的调用会原样返回那份待处理申请,而不会创建第二份。 处理结果会以单个 `Screentime.OverrideResult` webhook 异步送达,携带 `status: "granted" | "denied" | "expired"`。webhook 正文在 `state` 下包含与 `GET /screentime/get-state` 相同的结构,因此平台可以直接更新自身保存的状态,无需再次拉取。24 小时内未处理的申请会以 `status: "expired"` 触发 webhook。

POST
/screentime/request-override
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The kid's session the override is being requested for.

Response Body

application/json

application/json

curl -X POST "https://example.com/screentime/request-override" \  -H "Content-Type: application/json" \  -d '{    "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672"  }'
{  "id": "9d4e2f81-7a3b-4c56-8e90-1f2a3b4c5d6e",  "expiresAt": "2026-06-25T16:00:00Z"}

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

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

开始屏幕使用时间 POST

标记本产品上活动屏幕使用时间的开始。在屏幕使用时间处于活动状态期间,k-ID 会发送实时 webhook——`Screentime.BreakReminder`、`Screentime.LimitWarning` 和 `Screentime.LimitReached`——它们在越过阈值的那一刻触发,而不仅仅在使用结束时触发。 状态含义: * `accepted` - 屏幕使用时间已开始,或对已处于活动状态的会话的重试被幂等处理。 * `replaced` - 该 `sessionId` 的屏幕使用时间已处于活动状态时又传入了不同的 `id`;先前的屏幕使用时间被自动结束,其时长计入当天的屏幕使用量。当先前的屏幕使用时间从未被显式结束时(例如应用或设备重启后),可借此恢复。 每个 `sessionId` 同一时间只支持一段活动屏幕使用时间。调用必须实时进行——`timestamp` 的值不得早于 5 分钟前。