Endpointsスクリーンタイム

セッションの完了済みスクリーンタイム利用区間を送信する

k-IDセッションについて、完了済みのスクリーンタイム利用区間を1件以上送信します。各イベントは、利用がいつ始まり、どれだけ続いたかを記録します。利用時間が事後にしか分からない場合(区間をバッファリングして定期的にアップロードするバックエンドや、終了時にセッション合計を報告するゲームエンジンなど)にこのAPIを使用します。 受理された各区間の `durationSeconds` は、プレイヤーの当日のスクリーンタイム合計に加算されます。区間が保護者の設定したタイムゾーンで深夜0時をまたぐ場合は両方の日付に分割され、各日の合計が実際にその日に発生した利用時間を反映します。 イベントはそれぞれ独立して処理されます。レスポンスにはイベントごとのステータスが含まれます。 * `accepted` - 区間が記録され、当日の合計に加算されました。すでに受理済みの `id` を持つイベントを再送しても安全な無操作となり、再び `accepted` として数えられ、二重に加算されることはありません。そのため、ネットワーク障害後の再試行で二重計上されることはありません。 * `rejected` - 区間が検証に失敗しました。`reason` がどのルールに違反したかを示します。 セッションが存在しない場合や無効化されている場合は、バッチ全体が拒否されます。 リアルタイムの制限シグナル(`Screentime.LimitWarning`、`Screentime.LimitReached`、`Screentime.BreakReminder`)はこのAPIからは発火しません。しきい値を超えた時点でこれらの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"    }  ]}

スクリーンタイムの状態を取得する GET

`sessionId` に対する現在のスクリーンタイムの状態を返します。保護者が設定したルール、当日の利用状況、そして現時点でプレイを許可してよいかどうかが含まれます。プラットフォームは、セッション開始時と、`Screentime.LimitWarning`、`Screentime.LimitReached`、`Screentime.QuietHoursWarning`、`Screentime.QuietHoursReached` のWebhookを受信した後に、保持している状態を更新するためにこのAPIを呼び出します。 保護者がそのセッションのスクリーンタイムを設定していない場合、または設定済みでも制限の適用を無効にしている場合は `{ "enabled": false }` を返します。

スクリーンタイムの上限解除を申請する POST

子どもが当日の時間を延長したい場合や、有効な休止時間(quiet hours)を回避したい場合に、子どもに代わって上限解除の申請を送信します。k-IDは申請を記録し、承認または拒否を求めて保護者に通知します。子どもごとに冪等で、同じ子どもからの別の申請が保留中のあいだに呼び出した場合は、2つ目を作成せず、その保留中の申請をそのまま返します。 判断結果は非同期に、`status: "granted" | "denied" | "expired"` を伴う1件の `Screentime.OverrideResult` Webhookとして届きます。Webhookのボディは `state` の下に `GET /screentime/get-state` と同じ形式のデータを含むため、プラットフォームは追加の取得を行わずに保持している状態を直接更新できます。24時間以内に解決されなかった申請は、`status: "expired"` でWebhookを発火します。