UserBoost Documentation - Event Infrastructure for SaaS

Single Event API (Recommended)

The /v1/event endpoint is the primary way to track user events - simple, fast, and perfect for most applications:

Minimal Example (Required Fields Only)

cURL
Node.js
Python

curl -X POST https://api.userboo.st/v1/event \
  -H "Authorization: Bearer ub_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "button_clicked",
    "user": {"id": "user_123"}
  }'

📋 Standard Example (With Event Data)

cURL
Node.js
Python

curl -X POST https://api.userboo.st/v1/event \
  -H "Authorization: Bearer ub_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "button_clicked",
    "user": {"id": "user_123"},
    "properties": {
      "button": "signup_cta",
      "page": "homepage"
    }
  }'

📋 Field Requirements

Field	Required	Type	Description
✅ `event`	REQUIRED	`string`	Event name (e.g., “user_signed_up”)
✅ `user`	REQUIRED	`object`	User object with id and optional traits
❌ `timestamp`	Optional	`string`	ISO 8601 timestamp (defaults to now)
❌ `properties`	Optional	`object`	Event-specific data

📦 Batch Events API (Advanced)

For high-volume applications only - use /v1/events to send multiple events:

Event Tracking
User Identification

Track user actions - Creates event records with minimal payload size

cURL
Node.js
Python

curl -X POST https://api.userboo.st/v1/events \
  -H "Authorization: Bearer ub_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sent_at": "2025-01-15T10:00:00Z",
    "events": [{
      "type": "event",
      "event": "button_clicked",
      "user": {"id": "user_123"},
      "timestamp": "2025-01-15T10:00:00Z",
      "properties": {
        "button": "signup_cta",
        "page": "homepage"
      }
    }]
  }'

Use /v1/event for most applications - the batch endpoint is only needed for high-volume scenarios (100+ events per minute)

Browser SDK (Optional)

For frontend-only applications, you can use the JavaScript SDK:

Event Tracking
User Identification

// Browser Script Tag
ub.event("button_clicked", {
  id: "user_123",
  button: "signup_cta",
  page: "homepage"
});

Event Format & User Data

Flexible User Format

UserBoost supports two user formats - use the one that fits your needs:

Simple User ID (Minimal)
User Object (Rich Data)

Most common approach - Send just the user ID as a string

{
  "event": "user_signed_up",
  "user": {"id": "user_123"},
  "properties": {
    "source": "website"
  }
}

When to use:

You’re tracking events for existing users
User data is already stored in your system
You want minimal payload size

Properties vs Traits

Key Distinction: - Properties: Event-specific data (what happened during this event) - Traits: User-specific attributes (persistent info about who the user is)

Properties (Event Data)
Traits (User Data)

{
  "event": "purchase_completed",
  "user": {"id": "user_123"}, 
  "properties": {
    "amount": 99.00,
    "product": "pro_plan",
    "payment_method": "stripe",
    "discount_applied": "SAVE20"
  }
}

Use properties for:

Event context (what button was clicked)
Transaction details (amount, product)
Session information (page viewed)
Temporary state (current cart size)

Single Event API (Recommended)

For most use cases, use the /v1/event endpoint:

Basic Event
Batch Events API (Optional)

{
  "event": "user_signed_up",
  "user": {
    "id": "user_123",
    "email": "john@example.com",
    "traits": {
      "plan": "free"
    }
  },
  "timestamp": "2025-01-15T10:00:00Z",
  "properties": {
    "source": "website"
  }
}

Key Benefits:

Simple payload structure
Real-time event processing
Automatic context extraction (IP, User-Agent)
Optional timestamp (auto-generated if not provided)

Required Fields

Every event must include a user field and event field. The user field must be an object with at least an id property.

Direct API (Optimized)
Browser SDK

{
  "sent_at": "2025-01-15T10:00:00Z",
  "events": [{
    "type": "event",
    "event": "purchase_completed", // ✅ Required
    "user": {"id": "user_123"}, // ✅ Required (user object)
    "properties": {
      "amount": 99,
      "plan": "pro"
    }
  }]
}

Benefits: Smaller payloads compared to traditional analytics

Full Example

Browser Script Tag
NPM Package

ub.event("feature_used", {
  // User identification (required)
  id: "user_123",
  email: "john@example.com", // Recommended
  name: "John Doe", // Optional

  // Event properties (optional)
  feature: "analytics_dashboard",
  usage_count: 3,
  user_role: "admin",

  // Custom traits (optional)
  plan: "pro",
  signup_date: "2025-01-15",
  company: "Acme Corp",
});

Event Naming

Best Practices

✅ Good Event Names

user_signed_up - Clear action - profile_completed - Specific milestone
first_project_created - Meaningful achievement - payment_method_added
Precise user action - tutorial_finished - Clear completion state

❌ Avoid These Names

click - Too generic - user_action_performed - Vague - page_view_homepage - Usually not meaningful - button_1_clicked - Use descriptive names - internal_system_update - Not user-facing

Naming Convention

Use snake_case with descriptive, action-oriented names:

Browser Script Tag
NPM Package

// ✅ Recommended pattern: object_action_descriptor
ub.event("profile_completed", { id: "user_123" });
ub.event("project_created", { id: "user_123" });
ub.event("team_member_invited", { id: "user_123" });
ub.event("subscription_upgraded", { id: "user_123" });

// ✅ Also good: action_object pattern
ub.event("completed_onboarding", { id: "user_123" });
ub.event("viewed_pricing", { id: "user_123" });
ub.event("started_trial", { id: "user_123" });

Common Event Patterns

User Lifecycle Events

Track key moments in the user journey:

Registration
Onboarding
Engagement
Conversion

Browser Script Tag
NPM Package

// Account creation
ub.event("account_created", {
  id: "user_123",
  email: "john@example.com",
  signup_method: "google",
  utm_source: "facebook_ad",
  plan: "free"
});

// Email verification
ub.event("email_verified", {
  id: "user_123",
  verification_time: "2 minutes"
});

Feature Adoption

Track how users discover and adopt your features:

Browser Script Tag
NPM Package

// Feature discovery
ub.event("feature_discovered", {
  id: "user_123",
  feature: "advanced_analytics",
  discovery_method: "tooltip",
  days_since_signup: 5,
});

// First use
ub.event("feature_first_used", {
  id: "user_123",
  feature: "advanced_analytics",
  success: true,
  time_to_first_use: "2 days",
});

// Regular adoption
ub.event("feature_used_regularly", {
  id: "user_123",
  feature: "advanced_analytics",
  usage_count: 10,
  days_since_first_use: 7,
});

Team and Collaboration

For B2B SaaS, track team dynamics:

Browser Script Tag
NPM Package

// Team building
ub.event("team_member_invited", {
  id: "user_123",
  role: "admin",
  invite_method: "email",
  team_size: 3,
});

ub.event("team_member_joined", {
  id: "user_456", // The new team member's ID
  inviter_id: "user_123",
  role: "member",
  join_time: "2 hours",
});

// Collaboration
ub.event("project_shared", {
  id: "user_123",
  project_id: "proj_789",
  shared_with: "team",
  permission_level: "edit",
});

Event Properties

Property Guidelines

Recommended Properties
Avoid These

Browser Script Tag
NPM Package

ub.event("purchase_completed", {
  id: "user_123",
  
  // Quantitative properties
  amount: 99.00,
  item_count: 3,
  discount_percent: 10,
  
  // Categorical properties  
  plan: "pro",
  payment_method: "stripe",
  billing_cycle: "annual",
  
  // Boolean flags
  is_first_purchase: true,
  used_coupon: true,
  
  // Timing information
  time_to_purchase: "5 days",
  checkout_duration: "3 minutes"
});

Property Types & Examples

Type	Format	Use Cases	Example
String	`"value"`	Categories, IDs	`plan: "pro"`
Number	`42`, `99.99`	Counts, prices	`amount: 99.99`
Boolean	`true`/`false`	Flags	`is_trial: true`
Date	`"YYYY-MM-DD"`	Time tracking	`trial_end: "2025-02-15"`

Batching and Performance

Automatic Batching

UserBoost automatically batches events for optimal performance:

Browser Script Tag
NPM Package

// These events are batched together
ub.event("page_viewed", { id: "user_123", page: "dashboard" });
ub.event("button_clicked", { id: "user_123", button: "export" });
ub.event("file_downloaded", { id: "user_123", file: "report.pdf" });

// Sent as single API request after 10 seconds (default)

Manual Flushing

Force immediate sending when needed:

Browser Script Tag
NPM Package

// Important event that should be sent immediately
ub.event("payment_completed", {
  id: "user_123",
  amount: 99.99,
});

// Force send now (useful for page unload)
ub.flush();

Performance Tips

Optimize Event Volume

Browser Script Tag
NPM Package

// ✅ Track meaningful milestones
ub.event("onboarding_completed", {
  id: "user_123",
  steps_completed: 5,
  completion_time: "10 minutes"
});

// ❌ Don't track every micro-interaction
// ub.event("step_1_viewed", { id: "user_123" });
// ub.event("step_2_viewed", { id: "user_123" });
// ... (too granular)

Minimize Property Size

Browser Script Tag
NPM Package

// ✅ Concise, meaningful properties
ub.event("search_performed", {
  id: "user_123",
  query: "analytics",
  results_count: 15,
  category: "features"
});

// ❌ Avoid large text blobs
// Don't include entire HTML content or massive JSON objects

Error Handling

Client-Side Errors

UserBoost handles network errors gracefully:

Browser Script Tag
NPM Package

// Events are queued if offline
ub.event("offline_action", { id: "user_123" });

// Automatically retried when connection returns
// No additional code needed

Validation Errors

Common validation issues:

Missing User ID

Browser Script Tag
NPM Package

// ❌ This will fail
ub.event("button_clicked", {
  button: "signup"  // Missing required 'id' field
});

// ✅ Always include user ID
ub.event("button_clicked", {
  id: "user_123", // Required
  button: "signup"
});

Testing Events

Debug Mode

Enable debugging to see event details:

Browser Script Tag
NPM Package

// Enable debug mode
ub.debug(true);

// Events will now be logged to console
ub.event("test_event", {
  id: "test_user",
  test_property: "test_value"
});

// Console output:
// [UserBoost] Event: test_event
// [UserBoost] Data: {id: "test_user", test_property: "test_value"}
// [UserBoost] ✅ Queued for sending

Dashboard Testing

Enable Debug

Turn on debug mode in your code

Trigger Events

Perform actions in your app to generate events

Check Console

Verify events are logged without errors

View Dashboard

Go to Events → Live Stream to see events arrive

Quick Start (5 minutes)

Event Tracking

API Reference

Advanced Guides

Events API Reference

Single Event API (Recommended)

Minimal Example (Required Fields Only)

📋 Standard Example (With Event Data)

📋 Field Requirements

📦 Batch Events API (Advanced)

Browser SDK (Optional)

Event Format & User Data

Flexible User Format

Properties vs Traits

Single Event API (Recommended)

Required Fields

Full Example

Event Naming

Best Practices

Naming Convention

Common Event Patterns

User Lifecycle Events

Feature Adoption

Team and Collaboration

Event Properties

Property Guidelines

Property Types & Examples

Batching and Performance

Automatic Batching

Manual Flushing

Performance Tips

Error Handling

Client-Side Errors

Validation Errors

Testing Events

Debug Mode

Dashboard Testing

Quick Start (5 minutes)

Event Tracking

API Reference

Advanced Guides

​Single Event API (Recommended)

​Minimal Example (Required Fields Only)

​📋 Standard Example (With Event Data)

​📋 Field Requirements

​📦 Batch Events API (Advanced)

​Browser SDK (Optional)

​Event Format & User Data

​Flexible User Format

​Properties vs Traits

​Single Event API (Recommended)

​Required Fields

​Full Example

​Event Naming

​Best Practices

​Naming Convention

​Common Event Patterns

​User Lifecycle Events

​Feature Adoption

​Team and Collaboration

​Event Properties

​Property Guidelines

​Property Types & Examples

​Batching and Performance

​Automatic Batching

​Manual Flushing

​Performance Tips

​Error Handling

​Client-Side Errors

​Validation Errors

​Testing Events

​Debug Mode

​Dashboard Testing

Single Event API (Recommended)

Minimal Example (Required Fields Only)

📋 Standard Example (With Event Data)

📋 Field Requirements

📦 Batch Events API (Advanced)

Browser SDK (Optional)

Event Format & User Data

Flexible User Format

Properties vs Traits

Single Event API (Recommended)

Required Fields

Full Example

Event Naming

Best Practices

Naming Convention

Common Event Patterns

User Lifecycle Events

Feature Adoption

Team and Collaboration

Event Properties

Property Guidelines

Property Types & Examples

Batching and Performance

Automatic Batching

Manual Flushing

Performance Tips

Error Handling

Client-Side Errors

Validation Errors

Testing Events

Debug Mode

Dashboard Testing