> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userboo.st/llms.txt
> Use this file to discover all available pages before exploring further.

# Events API Reference

> Complete API reference for tracking user events with optimized payloads

## 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)

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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"}
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch('https://api.userboo.st/v1/event', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ub_live_your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        event: 'button_clicked',
        user: {id: 'user_123'}
      })
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post('https://api.userboo.st/v1/event',
      headers={
        'Authorization': 'Bearer ub_live_your_api_key_here',
        'Content-Type': 'application/json'
      },
      json={
        'event': 'button_clicked',
        'user': {'id': 'user_123'}
      }
    )
    ```
  </Tab>
</Tabs>

### 📋 Standard Example (With Event Data)

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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"
        }
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch('https://api.userboo.st/v1/event', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ub_live_your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        event: 'button_clicked',
        user: {id: 'user_123'},
        properties: {
          button: 'signup_cta',
          page: 'homepage'
        }
      })
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post('https://api.userboo.st/v1/event',
      headers={
        'Authorization': 'Bearer ub_live_your_api_key_here',
        'Content-Type': 'application/json'
      },
      json={
        'event': 'button_clicked',
        'user': {'id': 'user_123'},
        'properties': {
          'button': 'signup_cta',
          'page': 'homepage'
        }
      }
    )
    ```
  </Tab>
</Tabs>

#### 📋 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:

<Tabs>
  <Tab title="Event Tracking">
    **Track user actions** - Creates event records with minimal payload size

    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        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"
              }
            }]
          }'
        ```
      </Tab>

      <Tab title="Node.js">
        ```javascript theme={null}
        const response = await fetch('https://api.userboo.st/v1/events', {
          method: 'POST',
          headers: {
            'Authorization': 'Bearer ub_live_your_api_key_here',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            sent_at: new Date().toISOString(),
            events: [{
              type: 'event',
              event: 'button_clicked',
              user: {id: 'user_123'},
              timestamp: new Date().toISOString(),
              properties: {
                button: 'signup_cta',
                page: 'homepage'
              }
            }]
          })
        });
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        import requests
        from datetime import datetime

        response = requests.post('https://api.userboo.st/v1/events',
          headers={
            'Authorization': 'Bearer ub_live_your_api_key_here',
            'Content-Type': 'application/json'
          },
          json={
            'sent_at': datetime.utcnow().isoformat() + 'Z',
            'events': [{
              'type': 'event',
              'event': 'button_clicked',
              'user': {'id': 'user_123'},
              'timestamp': datetime.utcnow().isoformat() + 'Z',
              'properties': {
                'button': 'signup_cta',
                'page': 'homepage'
              }
            }]
          }
        )
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="User Identification">
    **Update user profiles** - Updates user information without creating events

    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        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": "identify",
              "user": {"id": "user_123"},
              "timestamp": "2025-01-15T10:00:00Z",
              "traits": {
                "email": "john@example.com",
                "name": "John Doe",
                "plan": "pro"
              }
            }]
          }'
        ```
      </Tab>

      <Tab title="Node.js">
        ```javascript theme={null}
        const response = await fetch('https://api.userboo.st/v1/events', {
          method: 'POST',
          headers: {
            'Authorization': 'Bearer ub_live_your_api_key_here',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            sent_at: new Date().toISOString(),
            events: [{
              type: 'identify',
              user: {id: 'user_123'},
              timestamp: new Date().toISOString(),
              traits: {
                email: 'john@example.com',
                name: 'John Doe',
                plan: 'pro'
              }
            }]
          })
        });
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        response = requests.post('https://api.userboo.st/v1/events',
          headers={
            'Authorization': 'Bearer ub_live_your_api_key_here',
            'Content-Type': 'application/json'
          },
          json={
            'sent_at': datetime.utcnow().isoformat() + 'Z',
            'events': [{
              'type': 'identify',
              'user': {'id': 'user_123'},
              'timestamp': datetime.utcnow().isoformat() + 'Z',
              'traits': {
                'email': 'john@example.com',
                'name': 'John Doe',
                'plan': 'pro'
              }
            }]
          }
        )
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

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

## Browser SDK (Optional)

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

<Tabs>
  <Tab title="Event Tracking">
    ```javascript theme={null}
    // Browser Script Tag
    ub.event("button_clicked", {
      id: "user_123",
      button: "signup_cta",
      page: "homepage"
    });
    ```
  </Tab>

  <Tab title="User Identification">
    ```javascript theme={null}
    // Browser Script Tag
    ub.identify({
      id: "user_123", 
      email: "john@example.com",
      name: "John Doe",
      plan: "pro"
    });
    ```
  </Tab>
</Tabs>

## Event Format & User Data

### Flexible User Format

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

<Tabs>
  <Tab title="Simple User ID (Minimal)">
    **Most common approach** - Send just the user ID as a string

    ```json theme={null}
    {
      "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
  </Tab>

  <Tab title="User Object (Rich Data)">
    **Include user details** - Send user information with traits

    ```json theme={null}
    {
      "event": "user_signed_up",
      "user": {
        "id": "user_123",
        "email": "john@example.com",
        "traits": {
          "plan": "premium",
          "company": "Acme Corp",
          "signup_date": "2025-01-15"
        }
      },
      "properties": {
        "source": "website",
        "utm_campaign": "growth_q1"
      }
    }
    ```

    **When to use:**

    * You're tracking new users
    * You want to update user information
    * You have rich user context to send
  </Tab>
</Tabs>

### Properties vs Traits

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

<Tabs>
  <Tab title="Properties (Event Data)">
    ```json theme={null}
    {
      "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)
  </Tab>

  <Tab title="Traits (User Data)">
    ```json theme={null}
    {
      "event": "profile_updated",
      "user": {
        "id": "user_123",
        "traits": {
          "email": "john@example.com",
          "plan": "premium",
          "company_size": "50-100",
          "industry": "saas"
        }
      }
    }
    ```

    **Use traits for:**

    * User demographics (age, location)
    * Account information (plan, role)
    * Preferences (timezone, language)
    * Company details (size, industry)
  </Tab>
</Tabs>

### Single Event API (Recommended)

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

<Tabs>
  <Tab title="Basic Event">
    ```json theme={null}
    {
      "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)
  </Tab>

  <Tab title="Batch Events API (Optional)">
    ```json theme={null}
    {
      "sent_at": "2025-01-15T10:00:00Z",
      "events": [{
        "type": "event",
        "event": "user_signed_up",
        "user": {
          "id": "user_123",
          "email": "john@example.com",
          "traits": {
            "plan": "free"
          }
        },
        "timestamp": "2025-01-15T10:00:00Z",
        "properties": {
          "source": "website"
        }
      }]
    }
    ```

    **Use for:**

    * High-volume data ingestion
    * Offline event collection
    * Bulk historical data import

    <Note>Most applications should use the single event API for simplicity</Note>
  </Tab>
</Tabs>

### Required Fields

<Info>
  Every event **must** include a `user` field and `event` field. The user field
  must be an object with at least an `id` property.
</Info>

<Tabs>
  <Tab title="Direct API (Optimized)">
    ```json theme={null}
    {
      "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
  </Tab>

  <Tab title="Browser SDK">
    ```javascript theme={null}
    ub.event("purchase_completed", {
      id: "user_123", // ✅ Required (converted to optimized format)
      amount: 99,
      plan: "pro",
    });
    ```
  </Tab>
</Tabs>

### Full Example

<Tabs>
  <Tab title="Browser Script Tag">
    ```javascript theme={null}
    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",
    });
    ```
  </Tab>

  <Tab title="NPM Package">
    ```javascript theme={null}
    UserBoost.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",
    });
    ```
  </Tab>
</Tabs>

## Event Naming

### Best Practices

<AccordionGroup>
  <Accordion title="✅ Good Event Names" icon="check">
    * `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
  </Accordion>

  <Accordion title="❌ Avoid These Names" icon="x">
    * `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
  </Accordion>
</AccordionGroup>

### Naming Convention

Use **snake\_case** with descriptive, action-oriented names:

<Tabs>
  <Tab title="Browser Script Tag">
    ```javascript theme={null}
    // ✅ 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" });
    ```
  </Tab>

  <Tab title="NPM Package">
    ```javascript theme={null}
    // ✅ Recommended pattern: object_action_descriptor
    UserBoost.event("profile_completed", { id: "user_123" });
    UserBoost.event("project_created", { id: "user_123" });
    UserBoost.event("team_member_invited", { id: "user_123" });
    UserBoost.event("subscription_upgraded", { id: "user_123" });

    // ✅ Also good: action_object pattern
    UserBoost.event("completed_onboarding", { id: "user_123" });
    UserBoost.event("viewed_pricing", { id: "user_123" });
    UserBoost.event("started_trial", { id: "user_123" });
    ```
  </Tab>
</Tabs>

## Common Event Patterns

### User Lifecycle Events

Track key moments in the user journey:

<Tabs>
  <Tab title="Registration">
    <Tabs>
      <Tab title="Browser Script Tag">
        ```javascript theme={null}
        // 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"
        });
        ```
      </Tab>

      <Tab title="NPM Package">
        ```javascript theme={null}
        // Account creation
        UserBoost.event("account_created", {
          id: "user_123",
          email: "john@example.com",
          signup_method: "google",
          utm_source: "facebook_ad",
          plan: "free"
        });

        // Email verification
        UserBoost.event("email_verified", {
          id: "user_123",
          verification_time: "2 minutes"
        });
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Onboarding">
    <Tabs>
      <Tab title="Browser Script Tag">
        ```javascript theme={null}
        // Profile setup
        ub.event("profile_completed", {
          id: "user_123",
          has_avatar: true,
          company_size: "1-10",
          use_case: "personal_projects"
        });

        // First value experience
        ub.event("first_project_created", {
          id: "user_123", 
          project_type: "website",
          template_used: "blank",
          time_to_create: "5 minutes"
        });

        // Feature discovery
        ub.event("key_feature_used", {
          id: "user_123",
          feature: "collaboration",
          first_use: true
        });
        ```
      </Tab>

      <Tab title="NPM Package">
        ```javascript theme={null}
        // Profile setup
        UserBoost.event("profile_completed", {
          id: "user_123",
          has_avatar: true,
          company_size: "1-10",
          use_case: "personal_projects"
        });

        // First value experience
        UserBoost.event("first_project_created", {
          id: "user_123", 
          project_type: "website",
          template_used: "blank",
          time_to_create: "5 minutes"
        });

        // Feature discovery
        UserBoost.event("key_feature_used", {
          id: "user_123",
          feature: "collaboration",
          first_use: true
        });
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Engagement">
    <Tabs>
      <Tab title="Browser Script Tag">
        ```javascript theme={null}
        // Regular usage
        ub.event("dashboard_viewed", {
          id: "user_123",
          session_length: "15 minutes",
          features_used: ["analytics", "reports"]
        });

        // Social actions
        ub.event("content_shared", {
          id: "user_123",
          share_method: "twitter",
          content_type: "project"
        });

        // Help seeking
        ub.event("help_article_viewed", {
          id: "user_123",
          article_id: "getting-started",
          time_spent: "3 minutes"
        });
        ```
      </Tab>

      <Tab title="NPM Package">
        ```javascript theme={null}
        // Regular usage
        UserBoost.event("dashboard_viewed", {
          id: "user_123",
          session_length: "15 minutes",
          features_used: ["analytics", "reports"]
        });

        // Social actions
        UserBoost.event("content_shared", {
          id: "user_123",
          share_method: "twitter",
          content_type: "project"
        });

        // Help seeking
        UserBoost.event("help_article_viewed", {
          id: "user_123",
          article_id: "getting-started",
          time_spent: "3 minutes"
        });
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Conversion">
    <Tabs>
      <Tab title="Browser Script Tag">
        ```javascript theme={null}
        // Purchase intent
        ub.event("pricing_viewed", {
          id: "user_123",
          plan_compared: ["pro", "enterprise"],
          time_on_page: "5 minutes"
        });

        // Upgrade process
        ub.event("checkout_started", {
          id: "user_123",
          plan: "pro",
          billing_cycle: "annual",
          discount_applied: "SAVE20"
        });

        // Successful conversion
        ub.event("subscription_created", {
          id: "user_123",
          plan: "pro",
          amount: 99,
          currency: "USD",
          trial_days: 14
        });
        ```
      </Tab>

      <Tab title="NPM Package">
        ```javascript theme={null}
        // Purchase intent
        UserBoost.event("pricing_viewed", {
          id: "user_123",
          plan_compared: ["pro", "enterprise"],
          time_on_page: "5 minutes"
        });

        // Upgrade process
        UserBoost.event("checkout_started", {
          id: "user_123",
          plan: "pro",
          billing_cycle: "annual",
          discount_applied: "SAVE20"
        });

        // Successful conversion
        UserBoost.event("subscription_created", {
          id: "user_123",
          plan: "pro",
          amount: 99,
          currency: "USD",
          trial_days: 14
        });
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

### Feature Adoption

Track how users discover and adopt your features:

<Tabs>
  <Tab title="Browser Script Tag">
    ```javascript theme={null}
    // 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,
    });
    ```
  </Tab>

  <Tab title="NPM Package">
    ```javascript theme={null}
    // Feature discovery
    UserBoost.event("feature_discovered", {
      id: "user_123",
      feature: "advanced_analytics",
      discovery_method: "tooltip",
      days_since_signup: 5,
    });

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

    // Regular adoption
    UserBoost.event("feature_used_regularly", {
      id: "user_123",
      feature: "advanced_analytics",
      usage_count: 10,
      days_since_first_use: 7,
    });
    ```
  </Tab>
</Tabs>

### Team and Collaboration

For B2B SaaS, track team dynamics:

<Tabs>
  <Tab title="Browser Script Tag">
    ```javascript theme={null}
    // 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",
    });
    ```
  </Tab>

  <Tab title="NPM Package">
    ```javascript theme={null}
    // Team building
    UserBoost.event("team_member_invited", {
      id: "user_123",
      role: "admin",
      invite_method: "email",
      team_size: 3,
    });

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

    // Collaboration
    UserBoost.event("project_shared", {
      id: "user_123",
      project_id: "proj_789",
      shared_with: "team",
      permission_level: "edit",
    });
    ```
  </Tab>
</Tabs>

## Event Properties

### Property Guidelines

<Tabs>
  <Tab title="Recommended Properties">
    <Tabs>
      <Tab title="Browser Script Tag">
        ```javascript theme={null}
        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"
        });
        ```
      </Tab>

      <Tab title="NPM Package">
        ```javascript theme={null}
        UserBoost.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"
        });
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Avoid These">
    <Tabs>
      <Tab title="Browser Script Tag">
        ```javascript theme={null}
        ub.event("button_clicked", {
          id: "user_123",
          
          // ❌ Too technical
          dom_element_id: "btn_cta_homepage_v2",
          css_class_name: "btn btn-primary btn-lg",
          
          // ❌ Auto-generated noise
          timestamp: Date.now(),
          random_uuid: "550e8400-e29b-41d4",
          session_id: "sess_abc123",
          
          // ❌ Sensitive information
          ip_address: "192.168.1.1", 
          user_agent: "Mozilla/5.0...",
          
          // ❌ Redundant data
          event_name_copy: "button_clicked"
        });
        ```
      </Tab>

      <Tab title="NPM Package">
        ```javascript theme={null}
        UserBoost.event("button_clicked", {
          id: "user_123",
          
          // ❌ Too technical
          dom_element_id: "btn_cta_homepage_v2",
          css_class_name: "btn btn-primary btn-lg",
          
          // ❌ Auto-generated noise
          timestamp: Date.now(),
          random_uuid: "550e8400-e29b-41d4",
          session_id: "sess_abc123",
          
          // ❌ Sensitive information
          ip_address: "192.168.1.1", 
          user_agent: "Mozilla/5.0...",
          
          // ❌ Redundant data
          event_name_copy: "button_clicked"
        });
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

### 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:

<Tabs>
  <Tab title="Browser Script Tag">
    ```javascript theme={null}
    // 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)
    ```
  </Tab>

  <Tab title="NPM Package">
    ```javascript theme={null}
    // These events are batched together
    UserBoost.event("page_viewed", { id: "user_123", page: "dashboard" });
    UserBoost.event("button_clicked", { id: "user_123", button: "export" });
    UserBoost.event("file_downloaded", { id: "user_123", file: "report.pdf" });

    // Sent as single API request after 10 seconds (default)
    ```
  </Tab>
</Tabs>

### Manual Flushing

Force immediate sending when needed:

<Tabs>
  <Tab title="Browser Script Tag">
    ```javascript theme={null}
    // 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();
    ```
  </Tab>

  <Tab title="NPM Package">
    ```javascript theme={null}
    // Important event that should be sent immediately
    UserBoost.event("payment_completed", {
      id: "user_123",
      amount: 99.99,
    });

    // Force send now (useful for page unload)
    UserBoost.flush();
    ```
  </Tab>
</Tabs>

### Performance Tips

<AccordionGroup>
  <Accordion title="Optimize Event Volume" icon="gauge-high">
    <Tabs>
      <Tab title="Browser Script Tag">
        ```javascript theme={null}
        // ✅ 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)
        ```
      </Tab>

      <Tab title="NPM Package">
        ```javascript theme={null}
        // ✅ Track meaningful milestones
        UserBoost.event("onboarding_completed", {
          id: "user_123",
          steps_completed: 5,
          completion_time: "10 minutes"
        });

        // ❌ Don't track every micro-interaction
        // UserBoost.event("step_1_viewed", { id: "user_123" });
        // UserBoost.event("step_2_viewed", { id: "user_123" });
        // ... (too granular)
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Minimize Property Size" icon="compress">
    <Tabs>
      <Tab title="Browser Script Tag">
        ```javascript theme={null}
        // ✅ 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
        ```
      </Tab>

      <Tab title="NPM Package">
        ```javascript theme={null}
        // ✅ Concise, meaningful properties
        UserBoost.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
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

## Error Handling

### Client-Side Errors

UserBoost handles network errors gracefully:

<Tabs>
  <Tab title="Browser Script Tag">
    ```javascript theme={null}
    // Events are queued if offline
    ub.event("offline_action", { id: "user_123" });

    // Automatically retried when connection returns
    // No additional code needed
    ```
  </Tab>

  <Tab title="NPM Package">
    ```javascript theme={null}
    // Events are queued if offline
    UserBoost.event("offline_action", { id: "user_123" });

    // Automatically retried when connection returns
    // No additional code needed
    ```
  </Tab>
</Tabs>

### Validation Errors

Common validation issues:

<Warning>
  **Missing User ID**

  <Tabs>
    <Tab title="Browser Script Tag">
      ```javascript theme={null}
      // ❌ 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"
      });
      ```
    </Tab>

    <Tab title="NPM Package">
      ```javascript theme={null}
      // ❌ This will fail
      UserBoost.event("button_clicked", {
        button: "signup"  // Missing required 'id' field
      });

      // ✅ Always include user ID
      UserBoost.event("button_clicked", {
        id: "user_123", // Required
        button: "signup"
      });
      ```
    </Tab>
  </Tabs>
</Warning>

## Testing Events

### Debug Mode

Enable debugging to see event details:

<Tabs>
  <Tab title="Browser Script Tag">
    ```javascript theme={null}
    // 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
    ```
  </Tab>

  <Tab title="NPM Package">
    ```javascript theme={null}
    // Enable debug mode
    UserBoost.debug(true);

    // Events will now be logged to console
    UserBoost.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
    ```
  </Tab>
</Tabs>

### Dashboard Testing

<Steps>
  <Step title="Enable Debug">Turn on debug mode in your code</Step>

  <Step title="Trigger Events">
    Perform actions in your app to generate events
  </Step>

  <Step title="Check Console">Verify events are logged without errors</Step>

  <Step title="View Dashboard">
    Go to Events → Live Stream to see events arrive
  </Step>
</Steps>