Skip to main content

​
When to Use Web Apps Integration

Perfect for web applications:
  • React, Vue, Angular, Svelte applications
  • Next.js, Nuxt.js, SvelteKit applications
  • Static websites with JavaScript
  • Progressive Web Apps (PWAs)
  • Any frontend running in a browser
Key benefits:
  • ✅ Real-time user interaction tracking
  • ✅ Automatic page view and navigation tracking
  • ✅ Easy integration with any framework
  • ✅ Works with existing code - no major changes
  • ✅ Client-side event queueing and retry logic

​
Quick Setup (5 minutes)

1

Get your API key

  1. Sign up at userboo.st
  2. Go to Settings → API Keys
  3. Copy your Client-side API key (starts with ub_live_)
Use the client-side API key for web apps, not the server-side key.
2

Choose your installation method

Pick the approach that fits your application:
  • NPM Package
  • Script Tag
  • Async Loader
Recommended for modern frameworks
npm install @userboost/sdk
# OR
yarn add @userboost/sdk

import { UserBoost } from '@userboost/sdk';

UserBoost.init({
  apiKey: 'ub_live_your_client_key_here',
  debug: process.env.NODE_ENV === 'development',
});
3

Track your first event

The API is identical across all installation methods:
// Track page views
ub.event('page_viewed', {
  user: {
    id: 'user_123',
    email: 'john@example.com'
  },
  properties: {
    page: '/dashboard',
    referrer: document.referrer
  }
});

// Track button clicks
ub.event('button_clicked', {
  user: { id: 'user_123' },
  properties: {
    button_text: 'Get Started',
    location: 'hero_section'
  }
});
4

Verify it's working

  1. Go to your UserBoost dashboard
  2. Navigate to Events → Live Stream
  3. Interact with your web app
  4. Events should appear in the dashboard within 30 seconds
Enable debug mode during development to see events in your browser console.

​
Framework Integration Patterns

UserBoost uses the same API everywhere. Here’s how to integrate it with popular frameworks:
  • React
  • Next.js
  • Vue.js
  • Angular
  • Vanilla JS
// App.js
import React, { useEffect } from 'react';
import { UserBoost } from '@userboost/sdk';

function App() {
  useEffect(() => {
    UserBoost.init({
      apiKey: process.env.REACT_APP_USERBOOST_API_KEY,
      debug: process.env.NODE_ENV === 'development'
    });

    // Track app load
    UserBoost.event('app_loaded', {
      user: { id: getCurrentUserId() },
      properties: { page: 'home' }
    });
  }, []);

  return <div>{/* Your app */}</div>;
}

// Components can track events anywhere
function SignupButton() {
  const handleClick = () => {
    UserBoost.event('signup_button_clicked', {
      user: { id: getCurrentUserId() },
      properties: { location: 'header' }
    });
  };

  return <button onClick={handleClick}>Sign Up</button>;
}

​
Common Web Event Patterns

​
Page Views and Navigation

// Manual page view tracking
ub.event('page_viewed', {
  user: { id: getCurrentUserId() },
  properties: {
    page: window.location.pathname,
    title: document.title,
    referrer: document.referrer,
    timestamp: new Date().toISOString()
  }
});

// Single Page App navigation
function trackPageView(route) {
  ub.event('page_viewed', {
    user: { id: getCurrentUserId() },
    properties: {
      page: route,
      previous_page: getPreviousRoute(),
      navigation_type: 'spa'
    }
  });
}

​
User Interactions

// Button clicks
document.querySelectorAll('button[data-track]').forEach(button => {
  button.addEventListener('click', () => {
    ub.event('button_clicked', {
      user: { id: getCurrentUserId() },
      properties: {
        button_text: button.textContent,
        button_id: button.id,
        location: button.dataset.track
      }
    });
  });
});

// Form submissions
function trackFormSubmission(formName, formData) {
  ub.event('form_submitted', {
    user: { id: getCurrentUserId() },
    properties: {
      form_name: formName,
      fields_completed: Object.keys(formData).length,
      form_url: window.location.pathname
    }
  });
}

​
User Onboarding Events

// User registration
ub.event('user_signed_up', {
  user: {
    id: newUser.id,
    email: newUser.email,
    traits: {
      signup_method: 'email',
      plan: 'free'
    }
  },
  properties: {
    referral_source: document.referrer,
    signup_page: window.location.pathname
  }
});

// Profile completion steps
ub.event('profile_step_completed', {
  user: { id: userId },
  properties: {
    step: 'basic_info',
    completion_percentage: 25,
    time_spent: calculateTimeSpent()
  }
});

// First key action
ub.event('first_project_created', {
  user: { id: userId },
  properties: {
    project_type: 'website',
    days_since_signup: getDaysSinceSignup(),
    onboarding_completed: true
  }
});

​
Advanced Features

​
User Identification

// Identify users when they log in
ub.identify({
  id: 'user_123',
  email: 'john@example.com',
  name: 'John Doe',
  traits: {
    plan: 'pro',
    signup_date: '2024-01-15',
    company: 'Acme Corp'
  }
});

// Update user traits
ub.identify({
  id: 'user_123',
  traits: {
    plan: 'enterprise', // Updated plan
    last_login: new Date().toISOString()
  }
});

​
Event Batching and Performance

// Events are automatically batched, but you can control it
ub.init({
  apiKey: 'your_key',
  batchSize: 10,        // Send events in batches of 10
  flushInterval: 5000,  // Auto-flush every 5 seconds
  maxRetries: 3         // Retry failed requests 3 times
});

// Manual queue management
ub.flush();                    // Send all queued events immediately
console.log(ub.getQueueLength()); // Check how many events are queued

​
Environment Configuration

// Development vs Production
const config = {
  development: {
    apiKey: 'ub_live_dev_key_here',
    debug: true,
    flushInterval: 1000  // Flush more frequently in dev
  },
  production: {
    apiKey: 'ub_live_prod_key_here',
    debug: false,
    flushInterval: 10000
  }
};

ub.init(config[process.env.NODE_ENV] || config.development);

​
Environment Variables

Set up your API keys securely: 
NEXT_PUBLIC_USERBOOST_API_KEY=ub_live_your_client_key_here
Client-side API keys are safe to expose in frontend code, but make sure you’re using the correct client-side key (not server-side).

​
Testing & Debugging

​
Debug Mode

// Enable detailed console logging
ub.init({
  apiKey: 'your_key',
  debug: true
});

// Or enable debug mode after initialization
ub.setDebug(true);

​
Test Events

// Send a test event to verify integration
ub.event('web_integration_test', {
  user: { id: `test_user_${Date.now()}` },
  properties: {
    test: true,
    browser: navigator.userAgent,
    timestamp: new Date().toISOString(),
    url: window.location.href
  }
});

​
Browser DevTools

With debug mode enabled, you’ll see detailed logs in the browser console: 
[UserBoost] Initializing with key: ub_live_***
[UserBoost] Tracking event: page_viewed
[UserBoost] Event queued. Queue length: 1
[UserBoost] Auto-flushing due to time window
[UserBoost] Sending 1 events to API
[UserBoost] Events sent successfully

​
Common Issues

Check these common causes:
  • Using server-side API key instead of client-side key
  • Missing required user.id field in events
  • Ad blockers blocking the UserBoost domain
  • Network connectivity issues
  • Browser extensions interfering with requests
Enable debug mode to see detailed error messages in console.
For CDN integration:
  • Check if CDN is accessible from your domain
  • Verify script URL is correct
  • Check browser network tab for loading errors
  • Try the async loader for better reliability
For NPM integration:
  • Ensure package is installed: npm list @userboost/sdk
  • Check import statements are correct
  • Verify build process includes the package
Type definitions are included automatically:
import { UserBoost, UserData, EventData } from '@userboost/sdk';

const userData: UserData = {
  id: 'user_123',
  email: 'john@example.com'
};

const eventData: EventData = {
  user: userData,
  properties: { action: 'signup' }
};

UserBoost.event('user_action', eventData);
Add UserBoost domains to your CSP:
<meta http-equiv="Content-Security-Policy"
      content="connect-src 'self' https://api.userboo.st;
               script-src 'self' https://cdn.userboo.st;">

​
Performance Optimization

​
Lazy Loading

// Load UserBoost only when needed
async function initUserBoost() {
  const { UserBoost } = await import('@userboost/sdk');

  UserBoost.init({
    apiKey: 'your_key',
    debug: false
  });

  return UserBoost;
}

// Use when user performs their first action
document.addEventListener('click', async () => {
  const ub = await initUserBoost();
  ub.event('first_interaction', {
    user: { id: getCurrentUserId() }
  });
}, { once: true });

​
Bundle Size Optimization

The UserBoost SDK is optimized for minimal bundle impact:
  • ESM build: ~22KB minified
  • Gzipped: ~8KB
  • Tree-shakeable: Only import what you use

​
What’s Next?

Track Events

Learn advanced event tracking patterns and user journey mapping.

User Identification

Set up user identification and trait management.
Your web application is now tracking user interactions! UserBoost will automatically build user journey funnels and help you identify where users get stuck in your onboarding flow.
⌘I