Skip to main content

Screentime

Screentime lets a parent decide how long their child can use a connected app, and when. The rules live in k-ID rather than in each app's own code, so a parent sets a school-night limit once for your product and it applies to that child's use of it. Usage is counted per child per day rather than per session, so closing your app and coming back doesn't reset today's total.

Your product does two things: report when a player is using it, and honor the verdict k-ID returns. k-ID holds the rules, counts the usage, evaluates the schedule, and tells you what the answer is now.

What a parent can set​

A parent configures screentime for their child in Family Connect. A schedule has three kinds of rule, and any of them can be absent:

  • Daily limits: a minutes ceiling per weekday. A day with no entry has no limit; a day set to 0 minutes allows no usage at all. This is how a parent gives a child two hours on school nights and three at the weekend.
  • Quiet hours: named windows with a start time, an end time, and the days they apply to, such as Bedtime from 21:00 to 07:00 on weekdays. Quiet hours are a calendar, not a budget: they apply at those times regardless of how much the child has used.
  • Break reminders: an interval after which a child in one unbroken session is prompted to take a break.

Every schedule carries a time zone. Times, weekdays, and the daily reset are all evaluated in it, so a limit resets at local midnight rather than at midnight UTC.

How usage is counted​

The daily counter is keyed to the child and the product, not to a session: one counter per child per product per local day. That's what makes the limit hold across a day of stopping and starting, and it's why today's total survives a player closing your app and reopening it.

For that to work the player has to resolve to the session you already hold for them. Store the kuid from the session and replay it rather than opening a fresh session per device. See Sessions.

The boundary​

k-ID tracks usage, evaluates the schedule, and reports the verdict. Your product decides what enforcement looks like in it.

k-ID never blocks a player, ends a session, signs anyone out, or dictates your UI. When a limit is reached, k-ID tells you that it was reached and when it lifts. Whether that means a full-screen block, a read-only mode, a saved checkpoint, or a gentle nudge is a product decision, and it's yours.

Content is outside screentime entirely. Screentime is about how long and when, never about what.

Warning before the wall​

A child who is cut off mid-activity loses work and learns nothing. So every limit in screentime has a signal that arrives before it lands:

BeforeAt
Screentime.LimitWarning at 15 and 5 minutes remainingScreentime.LimitReached when the daily limit applies
Screentime.QuietHoursWarning 15 minutes before a windowScreentime.QuietHoursReached when the window opens

Treat each pair as one behavior. The warning is where you tell the player and give them a chance to reach a save point. The second event is where the rule applies. Handling only the second event technically satisfies the API and defeats the design.

Warnings fire while the player is still in the session, which is only possible if your product reports session boundaries as they happen. See Reporting usage for why that shapes which ingestion path you pick.

Asking a parent for more time​

A child who hits a wall can ask instead of being stuck. Your product submits the ask through /screentime/request-override, k-ID notifies the parent, and the parent grants or denies it in Family Connect.

The outcome arrives as Screentime.OverrideResult with a status of granted, denied, or expired. A request the parent never answers expires after 24 hours, which is a normal outcome rather than a failure. A grant raises today's limit; it doesn't remove or change the schedule.

Screentime and activity​

Screentime is a counter over usage, and usage is one kind of activity a product reports to k-ID. Ending a live screentime session records the time as activity, so it also feeds the usage a parent sees in Family Connect. The two features are configured and integrated separately.

Next steps​