@multisite/analytics

Self-hosted analytics SDK for Nuxt 3 and vanilla JS. Track custom user events — clicks, page views, conversions — and display them in your AdminPanel dashboard.

Installation

npm install @multisite/analytics

Quick Start — Nuxt 3 Module (recommended)

1. Add module to nuxt.config.js

export default defineNuxtConfig({
  modules: ['@multisite/analytics/nuxt'],

  analytics: {
    key: process.env.ANALYTICS_KEY,       // ak_live_xxxx
    siteId: process.env.ANALYTICS_SITE_ID // your site ID
  }
})

2. Add keys to .env

ANALYTICS_KEY=ak_live_xxxxxxxxxxxxxxxxxxxx
ANALYTICS_SITE_ID=your-site-id

3. Track events in components

<script setup>
const { $analytics } = useNuxtApp()

function onButtonClick() {
  $analytics.track('button_click', { button_id: 'hero-cta', page: '/landing' })
}
</script>

That's it. Page views are tracked automatically on every route change.

Manual Init (any framework)

import analytics from '@multisite/analytics'

analytics.init('ak_live_xxxx', {
  siteId: 'your-site-id',
  autoPageTracking: false
})

analytics.track('hero_cta_click', { button: 'Get Started' })

API Reference

analytics.init(key, options?)

Initialize the SDK. Call once before any other method.

analytics.init('ak_live_xxxx', {
  siteId: 'your-site-id',
  autoPageTracking: true,
  batchSize: 10,
  flushInterval: 3000,
  debug: false,
  endpoint: 'https://your-api.com' // optional, custom server
})

| Option | Type | Default | Description | |--------|------|---------|-------------| | siteId | string | — | Required. Your site ID | | autoPageTracking | boolean | true | Automatically track page views on route change | | batchSize | number | 10 | How many events to accumulate before sending | | flushInterval | number | 3000 | Auto-send interval in ms | | debug | boolean | false | Print logs to console | | endpoint | string | auto | Custom API server URL |

analytics.track(eventName, properties?)

Track a custom event.

analytics.track('button_click', {
  button_id: 'hero-cta',
  text: 'Get Started',
  variant: 'A'
})

analytics.track('form_submit', {
  form_id: 'contact',
  step: 3
})

analytics.track('purchase', {
  plan: 'pro',
  amount: 29
})

| Param | Type | Required | Description | |-------|------|----------|-------------| | eventName | string | Yes | Event name. Use snake_case. Max 100 chars | | properties | object | No | Custom properties. Max 50 keys, string values max 500 chars |

analytics.page(url?, properties?)

Track a page view manually. Not needed if autoPageTracking: true.

analytics.page('/about', { title: 'About Us' })

// or auto-detect current URL
analytics.page()

analytics.identify(userId, traits?)

Link the current anonymous session to a known user. Call after login.

analytics.identify('user_123', {
  name: 'John Doe',
  plan: 'pro',
  registered_at: '2026-01-15'
})

All subsequent events in this session will include user_id: 'user_123'.

userId is your external user ID. It is stored only inside events, not separately.

analytics.flush()

Force-send all queued events immediately. Useful before page close.

window.addEventListener('beforeunload', () => analytics.flush())

In Nuxt 3 module mode this is handled automatically via app:beforeUnmount.

What the SDK collects automatically

These fields are added to every event without any extra code:

| Field | Source | Description | |-------|--------|-------------| | session_id | sessionStorage | Anonymous session ID. Lives until tab is closed | | url | window.location.href | Page URL at the time of the event | | referrer | document.referrer | Where the user came from | | timestamp | Date.now() | Client-side event time (ISO 8601) |

What the SDK does NOT collect: cookies, fingerprinting, canvas/font data, or any personal data unless you explicitly pass it in properties.

IP address and User-Agent are added server-side from request headers.

Event Queue & Retry

Events are batched and sent efficiently:

track() → queue
  queue.length >= batchSize  → flush immediately
  every flushInterval ms     → flush automatically
  page close (beforeunload)  → flush immediately

On server error (5xx):
  retry after 5s → 30s → 60s
  after 3 failed attempts → drop batch, console.warn

Events are not persisted between sessions (no localStorage). Closing a tab loses the unsent queue — that's why flush() on beforeunload matters.

Nuxt 3 Module Options

// nuxt.config.js
export default defineNuxtConfig({
  modules: ['@multisite/analytics/nuxt'],

  analytics: {
    key: 'ak_live_xxxx',       // Analytics Key from your AdminPanel
    siteId: 'site_abc123',     // Site ID from your AdminPanel
    autoPageTracking: true,    // default: true
    batchSize: 10,             // default: 10
    flushInterval: 3000,       // default: 3000ms
    debug: false,              // default: false
    endpoint: ''               // default: auto from key
  }
})

After init, $analytics is available globally:

<script setup>
const { $analytics } = useNuxtApp()

// or create a composable
export const useAnalytics = () => useNuxtApp().$analytics
</script>

Security Notes

• Analytics Key is different from your CMS API Key — rotating one does not affect the other
• The key is validated server-side via bcrypt hash — it is safe to expose in frontend config
• Rate limits: 50 requests/sec per IP, 500 requests/min per site
• Properties are sanitized: max 50 keys, no nested objects, string values max 500 chars

License

MIT