@thrivestack/analytics-browser/README.md

ThriveStack Analytics Platform - Comprehensive web analytics tracking with privacy-first approach

# 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

```bash
npm install @thrivestack/analytics-browser
```

### CDN

```html
<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

```typescript
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

```typescript
// 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:

```html
<!-- 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:

```typescript
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)

```html
<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

```typescript
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

```typescript
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:

```typescript
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<EmailAbuseResponse>)
- `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](LICENSE) file for details.

7AEUrifaYNTeWSwiWc4c1w

7AEUrifaYNTeWSwiWc4c1w

c49db0c8f6a52e8e63f9cb2974b21e4d