Event Types
The shape of every event the SDK sends
Event Types
What's actually being sent to the server? This page shows you.
BaseEvent
Every event has these fields. It's the foundation everything else builds on.
interface BaseEvent {
type: 'track' | 'identify' | 'page' | 'group';
timestamp: string;
anonymousId: string;
userId?: string;
sessionId?: string;
accountId?: string;
context?: EventContext;
}Prop
Type
TrackEvent
Created when you call track(). The most common event type.
interface TrackEvent extends BaseEvent {
type: 'track';
event: string;
properties?: Record<string, unknown>;
}Prop
Type
What it looks like:
{
"type": "track",
"event": "button_clicked",
"properties": {
"buttonId": "cta-hero",
"variant": "primary"
},
"timestamp": "2025-01-15T10:30:00.000Z",
"anonymousId": "anon_abc123",
"userId": "user_456",
"sessionId": "sess_789"
}IdentifyEvent
Created when you call identify(). Links the anonymous visitor to a known user.
interface IdentifyEvent extends BaseEvent {
type: 'identify';
userId: string;
traits?: UserTraits;
}Prop
Type
What it looks like:
{
"type": "identify",
"userId": "user_456",
"traits": {
"email": "jane@example.com",
"name": "Jane Doe",
"plan": "pro"
},
"timestamp": "2025-01-15T10:30:00.000Z",
"anonymousId": "anon_abc123"
}PageEvent
Created when you call page(). Tracks where users go.
interface PageEvent extends BaseEvent {
type: 'page';
name?: string;
properties?: Record<string, unknown>;
url: string;
referrer?: string;
}Prop
Type
What it looks like:
{
"type": "page",
"name": "Dashboard",
"properties": {
"section": "analytics"
},
"url": "https://app.example.com/dashboard",
"referrer": "https://app.example.com/login",
"timestamp": "2025-01-15T10:30:00.000Z",
"anonymousId": "anon_abc123",
"userId": "user_456"
}GroupEvent
Created when you call group(). Associates users with accounts/teams.
interface GroupEvent extends BaseEvent {
type: 'group';
accountId: string;
traits?: AccountTraits;
}Prop
Type
What it looks like:
{
"type": "group",
"accountId": "workspace_789",
"traits": {
"name": "Acme Corp",
"plan": "enterprise",
"mrr": 5000
},
"timestamp": "2025-01-15T10:30:00.000Z",
"anonymousId": "anon_abc123",
"userId": "user_456"
}EventContext
The environment info we automatically capture with every event.
interface EventContext {
library: {
name: string;
version: string;
};
userAgent: string;
locale: string;
timezone: string;
screen?: {
width: number;
height: number;
};
page?: {
url: string;
path: string;
referrer: string;
title: string;
};
}Prop
Type
What it looks like:
{
"library": {
"name": "@thisbefine/analytics",
"version": "0.1.0"
},
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
"locale": "en-US",
"timezone": "America/Los_Angeles",
"screen": {
"width": 1920,
"height": 1080
},
"page": {
"url": "https://app.example.com/dashboard",
"path": "/dashboard",
"referrer": "https://app.example.com/login",
"title": "Dashboard | My App"
}
}You get all of this for free. No extra code needed.
Batch Payload
Events don't go one at a time. They're batched for efficiency.
interface BatchPayload {
batch: Array<TrackEvent | IdentifyEvent | PageEvent | GroupEvent>;
}What an actual API request looks like:
{
"batch": [
{
"type": "page",
"name": "Homepage",
"url": "https://example.com/",
"timestamp": "2025-01-15T10:30:00.000Z",
"anonymousId": "anon_abc123"
},
{
"type": "track",
"event": "cta_clicked",
"properties": { "variant": "blue" },
"timestamp": "2025-01-15T10:30:05.000Z",
"anonymousId": "anon_abc123"
},
{
"type": "identify",
"userId": "user_456",
"traits": { "email": "jane@example.com" },
"timestamp": "2025-01-15T10:30:10.000Z",
"anonymousId": "anon_abc123"
}
]
}The SDK batches events automatically. You don't need to think about this unless you're curious about what's going over the wire.