Event model

Six categories#

Each event belongs to exactly one category. The dashboard uses it for the icon and colour in the Events tab, the user journey and the funnel step picker, and you can filter any analytics view by it.

When you don't pass a category

• screen is navigation and identify is identity.
• A track name starting with login_, signup_, sign_up_, logout, password_, mfa_ or otp_ is identity.
• Any other track is conversion.
• The list is fixed. The SDKs drop a category that isn't one of the five you can send (all but technical), log a warning and still send the event, so the server works one out. Sent straight to the ingest API, an unknown category rejects that event, and the response lists it under rejected.

Automatic events#

The SDKs send these for you. Their names start with $, which your own events can't use, so they never clash with yours. The dashboard shows them with friendly labels, such as "App opened".

Screen views can also carry load_ms (how long the screen took to show), previous_screen and, on the web, referrer.

What counts toward your plan

• Lifecycle events are free and recorded on every plan, including Free and Starter, so crash journeys show when a session started and ended. They never count toward the analytics meter.
• $click and $deep_link_opened are analytics events: Growth and Scale, and they count toward the meter like your own events.

Clicks on the web#

On Growth and Scale, the web SDK records clicks on buttons and links by default. It reads the element type, its id and up to 64 characters of visible text (or the aria-label). It never reads what users type into inputs.

Turn clicks off for a whole project in the dashboard under Settings → SDK (no release needed), or in code. The script tag also accepts data-autocapture-clicks="false".

import { init } from "@codeskop/tracker"; init({ apiKey: "cs_live_pk_…", autocapture: { clicks: false } }); // or, with the script tag:// <script src="…" data-codeskop-key="cs_live_pk_…" data-codeskop-autocapture-clicks="false"></script>

To skip one element and everything inside it, add data-codeskop-ignore:

<div data-codeskop-ignore>  <button>Not recorded</button></div>

On Android, iOS and Flutter, track the taps that matter with the interaction category:

// Mobile has no automatic tap capture. Track the taps that matter:Codeskop.track("delivery_method_selected", mapOf("method" to "pickup"), category = "interaction")

Codeskop.shared.track(name: "delivery_method_selected", properties: ["method": "pickup"], category: "interaction")

await Codeskop.track('delivery_method_selected',    properties: {'method': 'pickup'}, category: 'interaction');

The shared envelope#

Every event, from every platform, has the same shape. You don't build it yourself (the SDK does), but it helps to know what each event carries when you read exports or webhooks.

{  "event_id": "4b1e…",          // unique per event, used to drop duplicates  "type": "track",               // track, screen, identify, or a technical type  "occurred_at": "2026-10-16T09:41:07.120Z",  "session_id": "s_8f2c…",       // the session it happened in, on every event  "seq": 12,                     // order within the session  "user": {    "id": "u_1042",              // after identify()    "anonymous_id": "a_93d1…"    // before and after identify(); new after reset()  },  "payload": {    "name": "login_failed",    "category": "identity",    "properties": { "method": "password", "reason": "invalid_password", "attempt": 2 }  }}

Sessions#

• One rule on every platform: a session ends after 30 minutes without activity.
• On mobile the session is saved on the device, so reopening the app within 30 minutes continues it.
• On the web a session continues across page loads in the same tab. Closing or reloading the tab ends it with $session_ended (closed). Following a link within your site, or going back and forward, keeps it going.
• Every event carries the session_id, including errors, crashes and API calls. That is how a journey shows that a user dropped off right after a slow or failing request.

Anonymous users and login#

Before identify, events carry an anonymous id kept on the device and no user id. When the user signs in, everything that anonymous id did before is linked to them: the sign-up screens, the failed logins, the first visit. Funnels, paths and the user's journey all show it as one person.

Call reset() when a user logs out. The device gets a new anonymous id, so the next person on a shared phone or computer isn't merged into the last one.

Naming your events#

• snake_case, object first, then a verb in the past tense: order_completed, video_played.
• Name the outcome, not the button: payment_failed, not pay_button_tapped_error.
• Send failures as their own events with a reason. A failure you track is a funnel step you can measure.
• Put variable detail in properties, not the name: plan_selected with plan: "growth".

Recommended events#

These are suggestions, not built in. Using them makes funnels and journeys read the same across your apps.

1import { track } from "@codeskop/tracker";2 3// Category is optional. Without it, Codeskop works one out (see the table above).4track("login_failed", { method: "password", reason: "invalid_password" }, { category: "identity" });5track("filter_applied", { filter: "price", value: "under_1000" }, { category: "interaction" });6track("order_completed", { order_id: "o_77", value: 4200, currency: "KES" }); // conversion

1Codeskop.track(2    "login_failed",3    mapOf("method" to "password", "reason" to "invalid_password"),4    category = "identity",5)6Codeskop.track("order_completed", mapOf("order_id" to "o_77", "value" to 4200, "currency" to "KES"))

1Codeskop.shared.track(2    name: "login_failed",3    properties: ["method": "password", "reason": "invalid_password"],4    category: "identity"5)

1await Codeskop.track('login_failed',2    properties: {'method': 'password', 'reason': 'invalid_password'},3    category: 'identity');4await Codeskop.track('order_completed', properties: {'order_id': 'o_77', 'value': 4200});

Never send#

• Names, emails, phone numbers or addresses. Values that look like an email or phone number are replaced with [REDACTED].
• Passwords, OTP codes, card numbers, tokens or anything typed into a form.
• Free text users wrote, such as search queries or messages. Send a length or a category instead.
• Use your own user ids in identify, never an email address.

Next steps#