Event Tracking

Capture custom events, structured log messages, and session attributes. Events are queued locally and flushed to the backend in batches.

Quick Start

import WhatzBug from '@whatzbug/react-native';

// Track a product event
WhatzBug.track('purchase_completed', {
  productId: 'sku_001',
  amount: 29.99,
  currency: 'USD',
});

// Log a structured message
WhatzBug.log('info', 'User completed onboarding', {
  step: 'profile_setup',
  duration: 4500,
});

// Set a session attribute
WhatzBug.setAttribute('subscription_tier', 'pro');

API Reference

`track(name, payload?)`

Track a named event with optional structured payload.

Parameter	Type	Required	Description
`name`	`string`	Yes	Event name (e.g. 'purchase_completed')
`payload`	`Record<string, any>`	No	Structured event data

Note: Event names starting with $ are reserved for internal SDK events. Do not use the $ prefix for custom events.

`log(level, message, data?)`

Log a structured message. This is a convenience wrapper that emits a $log event.

Parameter	Type	Required	Description
`level`	`'debug' \| 'info' \| 'warn' \| 'error'`	Yes	Log severity level
`message`	`string`	Yes	Human-readable log message
`data`	`Record<string, unknown>`	No	Additional structured context

`setAttribute(key, value)`

Set a custom attribute on the current session. Attributes persist until the session ends or is cleared.

Parameter	Type	Required	Description
`key`	`string`	Yes	Attribute name
`value`	`string \| number \| boolean`	Yes	Attribute value

Event Pipeline

Events follow this path through the SDK:

track() creates an envelope with a timestamp, device ID, and session context.
The envelope is added to a persistent queue backed by AsyncStorage.
The queue flushes in batches (default: up to 50 events per flush, every 5 seconds).
On flush failure, events are returned to the queue for retry.

Debug mode: When debug is enabled, events are also tapped into the real-time WebSocket stream for instant visibility in the Desktop App.

Best Practices

Use descriptive, snake_case event names: checkout_started, item_added_to_cart.
Keep payload data flat and serializable. Avoid nested objects beyond one level.
Use setAttribute() for session-level context (user tier, app version, experiment group).
Use log() for diagnostic messages; use track() for business/product events.