Advanced Features

Learn about super properties, timed events, and debugging.

Super Properties

Register properties that are automatically included with every event. Useful for app version, environment, or user segment.

// Register properties (overwrites existing)
kitbase.register({
  app_version: '2.1.0',
  environment: 'production',
  platform: 'web',
});

// Register only if not already set
kitbase.registerOnce({
  first_seen: new Date().toISOString(),
});

// Remove a super property
kitbase.unregister('platform');

// Get all super properties
const props = kitbase.getSuperProperties();

// Clear all super properties
kitbase.clearSuperProperties();

Methods

Method	Description
register(properties)	Set properties (overwrites existing)
registerOnce(properties)	Set properties only if not already set
unregister(key)	Remove a specific property
getSuperProperties()	Get all registered properties
clearSuperProperties()	Remove all super properties

Use Cases

// Set app context on initialization
kitbase.register({
  app_version: '2.1.0',
  environment: process.env.NODE_ENV,
  build_number: 1234,
});

// Set user segment after login
kitbase.register({
  user_plan: user.plan,
  user_tier: user.tier,
});

// Track first visit (only set once)
kitbase.registerOnce({
  first_visit_date: new Date().toISOString(),
  acquisition_source: getUtmSource(),
});

In-Memory Storage

Super properties are stored in memory and reset when the page reloads. For persistent properties, store them and call register() on initialization.

Timed Events

Track how long an action takes by starting a timer and automatically including the duration when the event is tracked.

// Start timing
kitbase.timeEvent('Video Watched');

// ... user watches video ...

// Track event (duration is automatically included as $duration tag)
await kitbase.track({
  channel: 'engagement',
  event: 'Video Watched',
  tags: { video_id: 'abc123' },
});
// Result: tags include { video_id: 'abc123', $duration: 45000 } (ms)

Methods

Method	Description
timeEvent(eventName)	Start timing an event
cancelTimeEvent(eventName)	Cancel a timed event
getTimedEvents()	Get list of events being timed
getEventDuration(eventName)	Get current duration in ms

Examples

// Check active timers
const activeTimers = kitbase.getTimedEvents();
// => ['Video Watched', 'Checkout Flow']

// Get duration without tracking
const duration = kitbase.getEventDuration('Video Watched');
// => 45000 (ms)

// Cancel a timer
kitbase.cancelTimeEvent('Video Watched');

Use Cases

// Track checkout flow duration
kitbase.timeEvent('Checkout Completed');

// ... user completes checkout steps ...

await kitbase.track({
  channel: 'purchases',
  event: 'Checkout Completed',
  user_id: user.id,
  tags: {
    order_id: order.id,
    items_count: cart.items.length,
  },
});
// $duration automatically added

// Track time spent on page
kitbase.timeEvent('Page Viewed');

window.addEventListener('beforeunload', async () => {
  await kitbase.track({
    channel: 'engagement',
    event: 'Page Viewed',
    tags: { path: window.location.pathname },
  });
});

Debug Mode

Enable debug logging to troubleshoot issues.

const kitbase = new Kitbase({
  token: '<YOUR_API_KEY>',
  debug: true,
});

// Or toggle at runtime
kitbase.setDebugMode(true);

// Check if debug mode is enabled
if (kitbase.isDebugMode()) {
  console.log('Debug mode active');
}

Lifecycle

Properly shut down the SDK when your app closes.

// Flush any pending events and clean up
await kitbase.shutdown();

This ensures:

• All queued events are sent
• Timers are cleaned up
• Resources are released