Tracking Events

Learn how to track events, use channels, tags, and configure notifications.

Basic Tracking

await kitbase.track({
  channel: 'payments',
  event: 'New Subscription',
  user_id: 'user-123',
  icon: '💰',
  notify: true,
  description: 'User subscribed to premium plan',
  tags: {
    plan: 'premium',
    cycle: 'monthly',
    amount: 9.99,
  },
});

Parameters

Parameter	Type	Required	Description
channel	string	Yes	Category for the event (e.g., "payments", "users")
event	string	Yes	Name of the event (e.g., "New Subscription")
user_id	string	No	Identifier for the user
icon	string	No	Emoji or icon name
notify	boolean	No	Send real-time notification
description	string	No	Additional context
tags	object	No	Key-value metadata

Response

interface TrackResponse {
  id: string;        // Unique event ID (e.g., "evt_abc123")
  event: string;     // Event name
  timestamp: string; // ISO 8601 timestamp
}

Channels

Channels organize your events into logical categories. Use consistent channel names across your application:

Channel	Use Case
payments	Subscriptions, purchases, refunds, billing
users	Signups, logins, profile updates
errors	Application errors, exceptions, failures
notifications	Push notification delivery status
api	External API calls, webhooks received
system	Deployments, server events

Channel Naming

Use lowercase, plural nouns for channel names. This keeps your events organized and easy to filter.

Tags

Tags are key-value pairs that add context to your events. They support three types:

Type	Example
string	"premium"
number	99.99
boolean	true

tags: {
  plan: 'premium',           // string
  amount: 99.99,             // number
  is_first_purchase: true,   // boolean
  referral_code: 'SAVE20',   // string
}

Tag Naming

Use lowercase snake_case for tag names:

• user_type, plan_name, error_code
• Not: UserType, planName, ERROR-CODE

Automatic Tag Enrichment

The backend automatically enriches your events with additional context:

Tag	Description
__browser	Browser name (Chrome, Firefox, Safari)
__browser_version	Browser version
__os	Operating system (Windows, macOS, iOS)
__os_version	OS version
__device	Device type (desktop, mobile, tablet)
__country	Country (from IP)
__region	Region/State
__city	City
__session_id	Session identifier
__path	Page path
__referrer	Referrer URL
__utm_source	UTM source parameter
__utm_medium	UTM medium parameter
__utm_campaign	UTM campaign parameter

Query Filters

Use these enriched tags to filter events in the dashboard by browser, country, device, or UTM parameters.

Notifications

Set notify: true to receive real-time notifications when important events occur:

await kitbase.track({
  channel: 'payments',
  event: 'Payment Failed',
  user_id: 'user-123',
  icon: '🔴',
  notify: true,  // Get notified immediately
  tags: {
    amount: 99.99,
    error: 'card_declined',
  },
});

Good candidates for notifications:

• New signups and subscriptions
• Failed payments
• Critical errors
• Security events (login from new device)

Icons

Use emoji or named icons to make events visually distinct:

// Emoji icons
icon: '💰'  // Payments
icon: '👤'  // Users
icon: '🔴'  // Errors
icon: '✅'  // Success
icon: '🔔'  // Notifications
icon: '🚀'  // Deployments

Use Cases

Track User Signups

await kitbase.track({
  channel: 'users',
  event: 'User Signed Up',
  user_id: user.email,
  icon: '👤',
  notify: true,
  description: `New user from ${user.referralSource}`,
  tags: {
    source: user.referralSource,
    plan: 'free',
    country: user.country,
  },
});

Track Payments

await kitbase.track({
  channel: 'payments',
  event: 'Subscription Created',
  user_id: user.id,
  icon: '💰',
  notify: true,
  tags: {
    plan: subscription.plan,
    amount: subscription.amount,
    currency: 'USD',
    interval: 'monthly',
  },
});

Track Errors

process.on('uncaughtException', async (error) => {
  await kitbase.track({
    channel: 'errors',
    event: 'Uncaught Exception',
    icon: '🔴',
    notify: true,
    description: error.message,
    tags: {
      name: error.name,
      stack: error.stack?.slice(0, 500),
    },
  });
});

Track Feature Usage

await kitbase.track({
  channel: 'features',
  event: 'Export Generated',
  user_id: user.id,
  icon: '📊',
  tags: {
    format: 'pdf',
    pages: 15,
    duration_ms: 2340,
  },
});

Error Handling

See Error Handling for detailed error handling patterns.

TypeScript

import { AuthenticationError, ValidationError } from '@kitbase/analytics';

try {
  await kitbase.track({ channel: 'users', event: 'Signup' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid API key
  } else if (error instanceof ValidationError) {
    // Missing required field
  }
}

Dart (Coming Soon)

import 'package:kitbase/events.dart';

try {
  await kitbase.track(channel: 'users', event: 'Signup');
} on EventsAuthenticationException {
  // Invalid API key
} on EventsValidationException catch (e) {
  // Missing required field
  print('Missing field: ${e.field}');
}

PHP (Coming Soon)

use Kitbase\Events\AuthenticationException;
use Kitbase\Events\ValidationException;

try {
    $kitbase->track(new TrackOptions(
        channel: 'users',
        event: 'Signup',
    ));
} catch (AuthenticationException $e) {
    // Invalid API key
} catch (ValidationException $e) {
    // Missing required field
    echo "Missing field: " . $e->field;
}