ThriveStack Analytics Browser

A comprehensive web analytics tracking library with privacy-first approach, built for modern web applications.

Features

• Privacy-First: Respects Do Not Track settings and consent management
• Device Fingerprinting: Advanced device identification using FingerprintJS
• Location Tracking: IP-based geolocation with caching
• Event Tracking: Page visits, clicks, form interactions, and custom events
• SPA Support: Built-in support for Single Page Applications
• Subscription Management: Automatic subscription status checking
• Debug Mode: Comprehensive logging for development and troubleshooting

Installation

NPM Package

npm install @thrivestack/analytics-browser

CDN

<script
  src="https://thrivestack-temp-static-assets.s3.us-east-1.amazonaws.com/scripts/latest/thrivestack.js"
  data-api-key="YOUR_API_KEY"
  data-source="your-source-name"
></script>

Quick Start

1. Initialize ThriveStack

import * as thrivestack from '@thrivestack/analytics-browser';

// Initialize with your API key
await thrivestack.init('YOUR_API_KEY', 'your-source-name');

// Set user information
await thrivestack.setUser('[email protected]', 'user123', {
  name: 'John Doe',
  plan: 'premium',
});

// Set group/account information
await thrivestack.setGroup('account123', 'example.com', 'Example Corp', {
  industry: 'technology',
  size: 'enterprise',
});

2. Track Events

// Track a simple event
await thrivestack.track('button_clicked', {
  button_name: 'signup',
  page: 'homepage',
});

// Track with additional properties
await thrivestack.track('purchase_completed', {
  amount: 99.99,
  currency: 'USD',
  product_id: 'prod_123',
});

// Track multiple events using array type (ThriveStackEvent[])
await thrivestack.trackEvents([
  {
    event_name: 'user_action',
    properties: { action: 'login', method: 'email' },
    user_id: 'user123',
    timestamp: new Date().toISOString(),
  },
  {
    event_name: 'page_view',
    properties: { page: 'dashboard' },
    user_id: 'user123',
    timestamp: new Date().toISOString(),
  },
]);

3. Button Click Tracking

To automatically track button clicks, add the thrivestack-event CSS class to your elements:

<!-- Basic click tracking -->
<button class="thrivestack-event">Click me</button>

<!-- With custom activity name -->
<button class="thrivestack-event:signup_button">Sign Up</button>

<!-- With additional context -->
<button class="thrivestack-event:checkout" data-plan="premium">Checkout</button>

Note: Only elements with the thrivestack-event class will be tracked. This ensures privacy and prevents unwanted tracking.

4. Advanced Event Tracking

For more complex scenarios, you can use the array-based tracking functions:

import * as thrivestack from '@thrivestack/analytics-browser';

// Method 1: Using the exported trackEvents function
await thrivestack.trackEvents([
  {
    event_name: 'user_action',
    properties: { action: 'login', method: 'email' },
    user_id: 'user123',
    timestamp: new Date().toISOString(),
  },
  {
    event_name: 'page_view',
    properties: { page: 'dashboard' },
    user_id: 'user123',
    timestamp: new Date().toISOString(),
  },
]);

// Method 2: Using the instance directly
const instance = thrivestack.getInstance();
if (instance) {
  // Track multiple events at once
  await instance.track([
    {
      event_name: 'user_action',
      properties: { action: 'login', method: 'email' },
      user_id: 'user123',
      timestamp: new Date().toISOString(),
    },
    {
      event_name: 'page_view',
      properties: { page: 'dashboard' },
      user_id: 'user123',
      timestamp: new Date().toISOString(),
    },
  ]);
}

Configuration Options

Script Attributes (CDN)

<script
  src="https://thrivestack-temp-static-assets.s3.us-east-1.amazonaws.com/scripts/latest/thrivestack.js"
  data-api-key="YOUR_API_KEY"
  data-source="your-source-name"
  data-track-clicks="true"
  data-track-forms="true"
></script>

NPM Package Options

import * as thrivestack from '@thrivestack/analytics-browser';

await thrivestack.init('YOUR_API_KEY', 'your-source-name', {
  trackClicks: true, // Enable automatic click tracking
  trackForms: true, // Enable automatic form tracking

  enableConsent: true, // Enable consent management
  defaultConsent: false, // Default consent state
  sessionTimeout: 1800000, // Session timeout in milliseconds (30 min)
  debug: false, // Enable debug mode
});

Event Properties

The following properties are automatically included in all events:

• Page Information: page_title, page_url, page_path, page_referrer
• Device Context: device_id, session_id, source
• Location Data: ip_address, city, region, country, timezone
• Browser Info: language, viewport_height, viewport_width
• Timing: timestamp (ISO format)

Consent Management

import * as thrivestack from '@thrivestack/analytics-browser';

const instance = thrivestack.getInstance();
if (instance) {
  // Set consent for different tracking categories
  instance.setConsent('analytics', true); // Click and form tracking
  instance.setConsent('marketing', false); // UTM parameter tracking
  instance.setConsent('functional', true); // Page visit tracking (always enabled)
}

Debug Mode

Enable debug mode to see detailed logging:

import * as thrivestack from '@thrivestack/analytics-browser';

const instance = thrivestack.getInstance();
if (instance) {
  instance.enableDebugMode();
}

API Reference

Core Functions

• init(apiKey, source?, options?) - Initialize ThriveStack
• track(eventName, properties?) - Track a single event
• trackEvents(events[]) - Track multiple events using ThriveStackEvent[] array type
• setUser(email, userId, properties?) - Set user information
• setGroup(groupId, domain, name, properties?) - Set group information
• getInstance() - Get the ThriveStack instance
• isInitialized() - Check if ThriveStack is initialized

Instance Methods

• instance.track(events[]) - Track multiple events (accepts array)
• instance.setUser(userId, email, properties?) - Set user data
• instance.setGroup(groupId, domain, name, properties?) - Set group data
• instance.checkAbuseEmail(email) - Check email address for abuse (returns Promise)
• instance.enableDebugMode() - Enable debug logging
• instance.getDeviceId() - Get current device ID

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

License

MIT License - see LICENSE file for details.

7AEUrifaYNTeWSwiWc4c1w

7AEUrifaYNTeWSwiWc4c1w

c49db0c8f6a52e8e63f9cb2974b21e4d