> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tell.rs/llms.txt
> Use this file to discover all available pages before exploring further.

# Events & Properties

> Tell's event model — named events with custom key-value properties.

Events are the core of Tell's analytics. Every user action you want to measure — a page view, a purchase, a feature toggle — is tracked as a named event with optional properties.

## Tracking an event

```javascript theme={null}
tell.track('sign_up', { plan: 'free', source: 'landing_page' });
```

The first argument is the event name. The second is a properties object — any key-value pairs that add context. Properties can be strings, numbers, booleans, or nested objects.

## Event types

SDKs support several event types beyond basic tracking:

### track

Record a user action. This is what you'll use most.

```javascript theme={null}
tell.track('page_view', { url: '/pricing', referrer: '/home' });
tell.track('purchase', { plan: 'pro', amount: 49.99 });
```

### identify

Link a device to a known user. Call this when a user logs in or signs up.

```javascript theme={null}
tell.identify('user-123', {
  email: 'alex@example.com',
  name: 'Alex',
  plan: 'pro'
});
```

The second argument sets **user traits** — persistent properties associated with the user. Traits are stored separately from event properties and appear in user analytics.

### group

Associate a user with a company or team.

```javascript theme={null}
tell.group('company-456', {
  name: 'Acme Corp',
  plan: 'enterprise',
  employees: 150
});
```

### revenue

Track a purchase with structured fields.

```javascript theme={null}
tell.revenue({
  amount: 49.99,
  currency: 'USD',
  order_id: 'order-789'
});
```

### alias

Merge two user identities. Use this when you discover that two device IDs belong to the same person.

```javascript theme={null}
tell.alias('anonymous-device-id', 'known-user-id');
```

### context

Send device and session information. SDKs typically send this automatically.

```javascript theme={null}
tell.context({
  os: 'iOS',
  os_version: '17.2',
  app_version: '2.1.0',
  device_type: 'mobile'
});
```

## Properties

Properties are key-value pairs attached to events. They power breakdowns, filters, and custom metrics.

### Common patterns

```javascript theme={null}
// Page tracking
tell.track('page_view', { url: '/pricing', title: 'Pricing' });

// Feature usage
tell.track('feature_used', { feature: 'dark_mode', enabled: true });

// E-commerce
tell.track('add_to_cart', { product_id: 'sku-123', price: 29.99, quantity: 2 });
```

### Super properties

Register properties that are automatically attached to every event:

```javascript theme={null}
tell.register({ app_version: '2.1.0', environment: 'production' });
```

This saves you from passing the same properties on every `track` call.

### Before-send hooks

Modify or drop events before they leave the SDK:

```javascript theme={null}
tell.beforeSend((event) => {
  // Remove sensitive data
  delete event.properties.email;
  return event; // return null to drop the event
});
```

## Property breakdowns

Once your events have properties, you can break down any metric by any property value:

* "Daily active users by `country`"
* "Event count broken down by `plan`"
* "Revenue grouped by `source`"

See [Filtering](/analytics/filtering) for the full set of operators (equals, contains, greater than, regex, and more).

## Property aggregation

For numeric properties, you can compute aggregations:

* **Sum** — total revenue from `purchase.amount`
* **Average** — mean order value
* **Min / Max** — smallest and largest values
* **Count** — number of events with the property set

These work through the [Data Queries API](/api/queries) and on [dashboard boards](/analytics/boards).

## What's next

* [Users & Identity](/tracking/users-and-identity) — how identity resolution works
* [Sessions](/tracking/sessions) — session tracking details
* [SDKs](/tracking/sdks/javascript) — language-specific integration guides
* [Logs](/tracking/logs) — structured logging (separate protocol)