SDK Guide

getAssignment(experimentId, userId, context?)

Request a treatment assignment for a user. The bandit algorithm selects the best-performing variant based on historical data. When context is provided, contextual bandit algorithms can use it for smarter decisions.

Returns: Promise<Assignment>

// Basic assignment
const assignment = await bandit.getAssignment('exp-headline', 'user-123')

// With contextual features
const assignment = await bandit.getAssignment('exp-headline', 'user-123', {
  deviceType: 'mobile',
  location: 'US',
  timeOfDay: 'evening'
})

// Assignment shape
// {
//   assignmentId: "asgn_abc123",
//   treatmentId: "treat_xyz",
//   experimentId: "exp-headline",
//   userId: "user-123",
//   config: { content: "Try it free today!", color: "#4f46e5" }
// }

trackEvent(event)

Track an event using assignment-based attribution. This is the recommended approach because it ties the event directly to the assignment, ensuring accurate measurement even when users see multiple experiments.

// Track a conversion with revenue
bandit.trackEvent({
  assignmentId: assignment.assignmentId,
  eventType: 'CONVERSION',
  value: 29.99,
  metadata: { product: 'premium-plan' }
})

// Track a click
bandit.trackEvent({
  assignmentId: assignment.assignmentId,
  eventType: 'CLICK'
})

// Track a custom event
bandit.trackEvent({
  assignmentId: assignment.assignmentId,
  eventType: 'CUSTOM',
  metadata: { action: 'added-to-cart', sku: 'WIDGET-42' }
})

track(experimentId, treatmentId, userId, eventType?, value?, metadata?)

Legacy event tracking method that uses explicit IDs instead of an assignmentId. Events are queued and flushed automatically in batches.

// Legacy tracking (not recommended)
bandit.track(
  'exp-headline',
  'treat-a',
  'user-123',
  'CONVERSION',
  29.99,
  { product: 'premium-plan' }
)

flush()

Manually flush all queued events to the server. Events are normally sent automatically based on the batchSize and flushInterval configuration, but you can force a flush before a page unload or navigation.

Returns: Promise<void>

// Flush before the user leaves the page
window.addEventListener('beforeunload', () => {
  bandit.flush()
})

destroy()

Stop the auto-flush timer and flush any remaining queued events. Call this when your application unmounts or the client is no longer needed to prevent memory leaks.

Returns: void

// React cleanup example
useEffect(() => {
  const client = new BanditClient({ apiUrl, apiKey })
  // ... use client
  return () => client.destroy()
}, [])

// SPA route change cleanup
router.beforeEach(() => {
  bandit.destroy()
})