Skip to main content
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

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. 
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. 
tell.identify('user-123', {
  email: '[email protected]',
  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. 
tell.group('company-456', {
  name: 'Acme Corp',
  plan: 'enterprise',
  employees: 150
});

​
revenue

Track a purchase with structured fields. 
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. 
tell.alias('anonymous-device-id', 'known-user-id');

​
context

Send device and session information. SDKs typically send this automatically. 
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

// 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: 
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: 
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 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 and on dashboard boards.

​
Logs

Logs use the same pipeline but have their own fields: 
tell.log('error', 'Payment failed', {
  service: 'billing',
  error_code: 'CARD_DECLINED',
  user_id: 'user-123'
});

​
Severity levels

LevelWhen to use
emergencySystem is unusable
alertImmediate action needed
criticalCritical condition
errorError that needs attention
warningSomething unexpected
noticeNormal but noteworthy
infoInformational (default)
debugDebug details
traceVery detailed tracing

​
What’s next

  • SDKs — language-specific integration guides
  • Users & Identity — how identity resolution works
  • Sessions — session tracking details
  • Logs — structured logging in depth