Activity
Most of the k-ID API answers questions your product asks: how old is this player, what are they allowed to do, has a parent consented. Activity is the other direction. Your product reports what a child actually did, and k-ID turns those reports into something a trusted adult can see.
You decide what activity means for your product. Time in a chat feature, messages sent, items purchased, lessons completed: you declare the types that matter, and push records against them. k-ID stores and aggregates what you send.
What an activity record is
An activity record is a single, timestamped thing that happened in your product, attached to a k-ID session.
| Field | What it carries |
|---|---|
id | A UUID your product generates. Identifies the record for idempotency. |
type | The key of an activity type declared for your product in Compliance Studio. |
value | The measurement, in the shape the type's metric type declares. |
timestamp | When it happened, in UTC. Must be within the last seven days. |
attributes | Optional key/value metadata, limited to the attribute keys the type declares. |
The session is the unit of attribution. Records belong to the session you push them against, and the trusted-adult surfaces read one session per player for a product, so push all of a player's activity against the session you already hold for them rather than opening a new one per device.
Activity types
An activity type is a declaration: this product reports this kind of thing, measured this way. Types are configured per product in Compliance Studio, so adding one is a configuration change rather than an integration project. See Activity types.
Each type fixes a metric type, which determines the shape of every value your product pushes for it.
| Metric type | Value shape | Example |
|---|---|---|
duration | seconds | Time spent in a feature |
currency | amount (minor units) and currency (ISO 4217) | Purchases and other money amounts |
count | count | Discrete events, such as messages sent |
gauge | number | Fractional readings, such as a completion ratio |
boolean | bool | Something that either happened or didn't |
A record whose value doesn't match its type's metric type is rejected, and so is a record whose type your product hasn't declared.
What k-ID does with activity
Activity feeds the surfaces a trusted adult sees. In Family Connect, a linked adult opens one of the products their child plays and reads that product's activity on its own tab. A linked adult also receives a recurring digest email for the product, weekly by default, at a cadence they control. Both read aggregated activity rather than raw records.
What activity isn't
The boundary is deliberate, and worth stating plainly:
- k-ID stores and aggregates activity. It doesn't interpret or moderate the content of it.
- Nothing in activity ingestion blocks a child, changes a permission, or fires an intervention. Features that act on a child's behavior, such as screentime limits, are separate and read from this one.
- Activity is inbound only. There's no activity webhook event: your product pushes to k-ID and gets a per-record result in the response.
Screentime reporting is the same shape as activity ingestion: your app reports usage to k-ID with no parent setup required, and parent-facing controls are a separate, optional tier on top. See screentime's feature flags.
Privacy and attributes
Attributes are for dimensions you want a trusted adult to see broken out, such as which mode of your game the time was spent in. They aren't a general-purpose payload.
Two rules follow from that. A type declares the attribute keys it accepts, and records carrying any other key are rejected. And an attribute value that looks like personal data is rejected outright. Send an opaque identifier your own systems can resolve instead of the personal data itself.
Retention
k-ID keeps individual activity records for 90 days. Aggregated activity, which is what the trusted-adult surfaces read, is kept for up to 2 years. Erasing a session or a player erases the activity attributed to it.
Test and live
Activity behaves like the rest of the product configuration: an activity type declared in the product editor is local until you push it to an environment, and the endpoints serve whichever configuration your API key's mode points at. Declare a type, push to test, and verify with test API keys before publishing to live. See Testing and publishing.
Next steps
- Reporting usage: push activity records, screentime usage, and completed purchases, handle per-item results, and verify end to end.
- Activity types: declare types in Compliance Studio.
/activity/push: the endpoint reference.