@calico/analytics/README.md

Analytics SDK for Calico Dashboard - Easy integration for tracking user interactions and configurations

# @calico/analytics

Official Analytics SDK for Calico Dashboard - Track user interactions, configurations, and e-commerce events with ease.

## Features

- 🚀 **Easy Integration** - Simple setup with auto-tracking capabilities
- 📊 **Comprehensive Event Tracking** - Track views, interactions, configurations, and purchases
- 🔄 **Automatic Batching** - Efficiently batch events to reduce API calls
- 🎯 **Session Management** - Automatic session tracking and user identification
- 🛡️ **Type-Safe** - Full TypeScript support with type definitions
- ⚡ **Performance Optimized** - Minimal bundle size with smart event queuing
- 🔌 **Self-Registration** - Apps can auto-register to get API keys

## Installation

```bash
npm install @calico/analytics
```

or

```bash
yarn add @calico/analytics
```

or

```bash
pnpm add @calico/analytics
```

## Quick Start

### Basic Setup

```javascript
import { init, track } from '@calico/analytics'

// Initialize the SDK with your API key
const analytics = init({
  apiKey: 'your-api-key-here',
  debug: true // Enable debug logging in development
})

// Track a page view
track('VIEW')

// Track an interaction with metadata
track('INTERACT', {
  button: 'add-to-cart',
  product: 'custom-chair'
})

// Track a purchase with value
track('PURCHASE', {
  orderId: '12345',
  products: ['chair', 'table']
}, 299.99)
```

### Auto-Registration (for new apps)

If you don't have an API key yet, you can auto-register your app:

```javascript
import { autoRegister, init } from '@calico/analytics'

// Auto-register your app
const apiKey = await autoRegister('My Awesome App', 'https://myapp.com')

// Initialize with the received API key
const analytics = init({ apiKey })
```

## Configuration Options

```typescript
interface CalicoAnalyticsConfig {
  apiKey: string           // Required: Your API key
  endpoint?: string        // Optional: Custom endpoint (default: Calico Dashboard)
  debug?: boolean          // Optional: Enable debug logging (default: false)
  autoTrack?: boolean      // Optional: Auto-track page views and clicks (default: true)
  batchSize?: number       // Optional: Events per batch (default: 10)
  flushInterval?: number   // Optional: Auto-flush interval in ms (default: 30000)
}
```

## Event Types

The SDK supports the following event types:

- `VIEW` - Page or screen views
- `INTERACT` - User interactions (clicks, taps, etc.)
- `CONFIGURE` - Product configuration changes
- `SHARE` - Social sharing actions
- `EXPORT` - Data or configuration exports
- `AR_VIEW` - Augmented Reality views
- `ADD_TO_CART` - E-commerce cart additions
- `PURCHASE` - Completed purchases

## API Reference

### `init(config: CalicoAnalyticsConfig)`

Initialize the analytics SDK with your configuration.

```javascript
const analytics = init({
  apiKey: 'your-api-key',
  debug: true,
  batchSize: 20,
  flushInterval: 60000 // 1 minute
})
```

### `track(event: AnalyticsEvent, metadata?: object, value?: number)`

Track an event with optional metadata and value.

```javascript
// Simple event
track('VIEW')

// Event with metadata
track('INTERACT', {
  element: 'button',
  action: 'click',
  label: 'Subscribe'
})

// Event with value (e.g., purchase amount)
track('PURCHASE', { orderId: '123' }, 99.99)
```

### `identify(userId: string, traits?: object)`

Identify a user and optionally set their traits.

```javascript
identify('user-123', {
  name: 'John Doe',
  email: 'john@example.com',
  plan: 'premium'
})
```

### `flush()`

Manually flush the event queue to send all pending events.

```javascript
await flush()
```

### `reset()`

Clear the current session and user data.

```javascript
reset()
```

## Advanced Usage

### Custom Event Tracking

```javascript
// Track a complex configuration
track('CONFIGURE', {
  product: 'custom-furniture',
  configuration: {
    material: 'oak',
    color: 'natural',
    dimensions: {
      width: 120,
      height: 75,
      depth: 60
    }
  },
  price: 599.99
}, 599.99)
```

### Manual Session Management

```javascript
import { init, track, reset } from '@calico/analytics'

const analytics = init({ apiKey: 'your-api-key' })

// Start a new session
reset()

// Track events in the session
track('VIEW', { page: '/products' })
track('INTERACT', { action: 'filter', category: 'chairs' })

// End session and flush events
await flush()
```

### Disable Auto-Tracking

```javascript
const analytics = init({
  apiKey: 'your-api-key',
  autoTrack: false // Disable automatic tracking
})

// Now you have full control over what gets tracked
document.getElementById('cta-button').addEventListener('click', () => {
  track('INTERACT', {
    button: 'cta',
    location: 'hero-section'
  })
})
```

## React Integration Example

```jsx
import { useEffect } from 'react'
import { init, track, identify } from '@calico/analytics'

function App() {
  useEffect(() => {
    // Initialize on app mount
    init({ apiKey: process.env.REACT_APP_CALICO_API_KEY })

    // Identify user if logged in
    const user = getCurrentUser()
    if (user) {
      identify(user.id, {
        name: user.name,
        email: user.email
      })
    }
  }, [])

  const handlePurchase = (product, price) => {
    track('PURCHASE', {
      productId: product.id,
      productName: product.name
    }, price)
  }

  return (
    // Your app components
  )
}
```

## Next.js Integration Example

```jsx
// pages/_app.js or app/layout.tsx
import { useEffect } from 'react'
import { init } from '@calico/analytics'

export default function MyApp({ Component, pageProps }) {
  useEffect(() => {
    init({
      apiKey: process.env.NEXT_PUBLIC_CALICO_API_KEY,
      debug: process.env.NODE_ENV === 'development'
    })
  }, [])

  return <Component {...pageProps} />
}
```

## Browser Support

The SDK supports all modern browsers:
- Chrome/Edge 80+
- Firefox 75+
- Safari 13.1+
- Opera 67+

## License

MIT

## Support

For issues, questions, or feature requests, please visit our [GitHub repository](https://github.com/calico-media/analytics-sdk) or contact support@calico.media.