@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

npm install @calico/analytics

or

yarn add @calico/analytics

or

pnpm add @calico/analytics

Quick Start

Basic Setup

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:

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

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.

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.

// 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.

identify('user-123', {
  name: 'John Doe',
  email: '[email protected]',
  plan: 'premium'
})

flush()

Manually flush the event queue to send all pending events.

await flush()

reset()

Clear the current session and user data.

reset()

Advanced Usage

Custom Event Tracking

// 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

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

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

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

// 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 or contact [email protected].