Offline & Retry

Queueing, retries, and unload delivery behavior

Queueing model

  • track() pushes events to an in-memory queue immediately
  • The SDK schedules a flush every ~1 second when queue is non-empty
  • analytics.flush() forces an immediate send attempt
analytics.track('checkout_started')
analytics.track('checkout_completed', { order_id: 'ord_123' })
analytics.flush()

Retry behavior

Failed batches retry with exponential backoff + jitter using defaults:maxRetries: 3, baseDelay: 1000,maxDelay: 30000.

Status/ErrorBehavior
429Retries using Retry-After (or 60s default)
5xxRetries with backoff
Network errorsRetries with backoff
Other 4xxNo retry

Offline persistence

  • Pending events are persisted in localStorage as ra_offline_queue
  • Stored queue is restored when the client initializes
  • Storage is capped at 1000 events

Unload behavior

On visibility change / unload, the SDK attempts delivery withnavigator.sendBeacon, with sync XHR fallback if Beacon is unavailable.

Lifecycle helpers

const pending = analytics.getQueueSize()

analytics.shutdown() // persists pending events + removes listeners

Callbacks

const analytics = createClient({
  publicKey: 'pk_live_xxx',
  onError: (error, events) => {
    console.error(error.message, events.length)
  },
  onSuccess: (events) => {
    console.log('batch sent', events.length)
  },
})

Next Steps