Package Exports

@thrivestack/analytics-browser
@thrivestack/analytics-browser/development
@thrivestack/analytics-browser/production

Readme

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('user@example.com', '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)

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.reportEmailAbuse(email) - Report 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

c49db0c8f6a52e8e63f9cb2974b21e4d