Offline Support

Queue events when offline and automatically send them when the connection is restored.

Overview

The offline queue provides reliable event delivery even when users have intermittent connectivity:

• Automatic queueing: Events are stored locally when offline
• Automatic syncing: Queued events are sent when back online
• Durable storage: Uses IndexedDB for persistence (browser)
• Retry with backoff: Failed events are retried with exponential backoff

Configuration

const kitbase = new Kitbase({
  token: '<YOUR_API_KEY>',
  offline: {
    enabled: true,
    maxQueueSize: 1000,        // Max events to queue
    flushInterval: 30000,      // Flush every 30 seconds
    flushBatchSize: 50,        // Events per batch
    maxRetries: 3,             // Max retry attempts
    retryBaseDelay: 1000,      // Initial retry delay
  },
});

Options

Option	Default	Description
enabled	false	Enable offline queue
maxQueueSize	1000	Maximum events to queue
flushInterval	30000	Flush interval in ms
flushBatchSize	50	Events per flush batch
maxRetries	3	Max retry attempts
retryBaseDelay	1000	Base delay for exponential backoff

How It Works

Event Flow

User action
    ↓
track() called
    ↓
┌─────────────────┐
│ Online?         │
└─────────────────┘
    │         │
   Yes        No
    ↓         ↓
Send to    Queue in
  API      IndexedDB
    │         │
    │    ┌────┴────┐
    │    │ Online  │←── Network restored
    │    │ event   │
    │    └────┬────┘
    │         ↓
    │    Flush queue
    ↓         ↓
   Done      Done

Retry Logic

Failed events are retried with exponential backoff:

Attempt	Delay
1st	1 second
2nd	2 seconds
3rd	4 seconds
After 3	Event dropped

Queue Management

Get Queue Statistics

const stats = await kitbase.getQueueStats();
// => {
//   pending: 15,    // Events waiting to be sent
//   failed: 2,      // Events that failed (will retry)
//   total: 17       // Total events in queue
// }

Manual Flush

Force send all queued events:

await kitbase.flushQueue();

Clear Queue

Remove all queued events without sending:

await kitbase.clearQueue();

Storage

Browser (IndexedDB)

In browsers, the queue uses IndexedDB via Dexie for durable storage:

• Events persist across page reloads
• Storage survives browser restarts
• Automatic cleanup after successful send

Node.js / Unsupported Environments

Falls back to in-memory storage:

• Events are lost on process restart
• Suitable for server-side with reliable connectivity

Best Practices

Mobile Apps

Enable offline mode for mobile applications:

const kitbase = new Kitbase({
  token: '<YOUR_API_KEY>',
  offline: {
    enabled: true,
    maxQueueSize: 500,      // Lower limit for mobile
    flushInterval: 60000,   // Flush every minute
    flushBatchSize: 25,     // Smaller batches
  },
});

Progressive Web Apps

const kitbase = new Kitbase({
  token: '<YOUR_API_KEY>',
  offline: {
    enabled: true,
    maxQueueSize: 1000,
  },
});

// Flush on service worker sync
self.addEventListener('sync', async (event) => {
  if (event.tag === 'kitbase-sync') {
    event.waitUntil(kitbase.flushQueue());
  }
});

Critical Events

For critical events, check queue status after tracking:

await kitbase.track({
  channel: 'payments',
  event: 'Payment Completed',
  user_id: user.id,
  notify: true,
  tags: { order_id: order.id },
});

// Check if event was queued
const stats = await kitbase.getQueueStats();
if (stats.pending > 0) {
  // Event was queued (offline)
  showOfflineIndicator();
}

Limitations

Limitation	Description
Queue size	Events are dropped when queue is full
Retry limit	Events are dropped after max retries
Storage quota	IndexedDB has browser-specific limits
Order guarantee	Events may be delivered out of order

Queue Overflow

When the queue reaches maxQueueSize, new events are dropped. Monitor queue stats for critical applications.