Analytics Insights SDK

A universal analytics SDK for TypeScript, JavaScript, React, and Next.js with SSR support.

Installation

npm install analytics-insights

Features

• 🚀 Universal: Works in TypeScript, JavaScript, React, and Next.js
• 🔒 SSR-Safe: No window/document access until client-side initialization
• 🎯 Type-Safe: Full TypeScript support with comprehensive type definitions
• 📦 Multiple Builds: ESM, CommonJS, and UMD builds included
• ⚡ Auto-Capture: Automatically tracks page views, clicks, forms, and scroll depth
• 🛡️ Error Handling: Graceful error handling with console warnings

Automatic Event Tracking

The SDK automatically captures these events without any additional code:

• Page Views: Automatic page view tracking on initialization and navigation
• Session Events: Session start, page visibility changes, page unload
• User Interactions: Link clicks, form submissions
• Engagement: Scroll depth milestones (25%, 50%, 75%, 90%, 100%)
• Performance: Web vitals and page performance metrics

Quick Start

Plain JavaScript

import analyticsInsights from 'analytics-insights'

// 1. Initialize with your API key
analyticsInsights.init('your_api_key_here')

// 2. Track events
analyticsInsights.capture('button_clicked', {
  button_name: 'signup'
})

// 3. Identify users
analyticsInsights.identify('user123', {
  email: '[email protected]'
})

React

import React, { useEffect } from 'react'
import analyticsInsights from 'analytics-insights'

function App() {
  useEffect(() => {
    // 1. Initialize with your API key
    analyticsInsights.init('your_api_key_here')
  }, [])

  const handleClick = () => {
    // 2. Track events
    analyticsInsights.capture('button_clicked')
  }

  return <button onClick={handleClick}>Track Click</button>
}

Next.js (App Router)

'use client'

import { useEffect } from 'react'
import analyticsInsights from 'analytics-insights'

export default function ClientAnalytics() {
  useEffect(() => {
    // 1. Initialize with your API key
    analyticsInsights.init('your_api_key_here')

    // 2. Track page view
    analyticsInsights.capture('page_view')
  }, [])

  return null
}

Browser Script Tag (UMD)

<script src="https://cdn.mydomain.com/analytics-insights.min.js"></script>
<script>
  // 1. Initialize with your API key
  analyticsInsights.init('your_api_key_here')

  // 2. Track events
  analyticsInsights.capture('page_view')
</script>

API Reference

analyticsInsights.init(apiKey, options?)

Initialize the Analytics Insights SDK.

Parameters:

• apiKey (string): Your analytics API key
• options (AnalyticsOptions, optional): Configuration options

Default Options:

{
  api_host: 'https://analytics.senseinsights.vteamslabs.com',
  person_profiles: 'identified_only',
  debug: false,
  disable_session_recording: false
}

analyticsInsights.capture(event, properties?)

Capture an analytics event.

Parameters:

• event (string): The name of the event to track
• properties (Record<string, any>, optional): Event properties

analyticsInsights.identify(distinctId, properties?)

Identify a user.

Parameters:

• distinctId (string): Unique identifier for the user
• properties (Record<string, any>, optional): User properties

analyticsInsights.reset()

Reset the user session.

Properties

• analyticsInsights.initialized (boolean): Check if SDK is initialized
• analyticsInsights.currentApiKey (string | null): Get current API key

TypeScript Support

The SDK includes comprehensive TypeScript definitions:

import analyticsInsights, { AnalyticsOptions } from 'analytics-insights'

const options: AnalyticsOptions = {
  api_host: 'https://your-analytics-instance.com',
  debug: true,
  person_profiles: 'identified_only'
}

analyticsInsights.init('your_api_key', options)

SSR Safety

The SDK automatically detects server-side environments and:

• Prevents initialization on the server
• Shows console warnings for server-side calls
• Safely ignores events captured on the server
• Only activates on client-side

Build and Development

# Install dependencies
npm install

# Build the package
npm run build

# Development with watch mode
npm run dev

# Clean build artifacts
npm run clean

License

MIT