Technical Documentation — SDKs and API

SDK Quick Start Guide

InsightPro provides three official SDKs for seamless integration across platforms. Each bundle now ships with BullMQ ingestion hints, offline persistence, and production-ready ESM/CJS/UMD builds.

JavaScript/TypeScript SDK

v1.0.0 • 77.5 kB

BullMQ-ready analytics with offline queueing and ingestion controls

insightpro-ai-sdk-js

Browser SDK

v1.0.0 • 43.8 kB

For web applications with UMD, ESM, and CommonJS support

insightpro-ai-sdk-browser

React Native SDK

v1.0.0 • 14.8 kB

For iOS and Android mobile applications

insightpro-ai-sdk-react-native

JavaScript/TypeScript SDK

Installation

bash

npm install insightpro-ai-sdk-js

Basic Usage

Initialize and Track Events

typescript

import InsightPro from 'insightpro-ai-sdk-js';

// Initialize the SDK
const analytics = new InsightPro({
  endpoint: 'https://api.insightpro-ai.com',
  tenantId: 'your_tenant_id',
  apiKey: 'your_api_key_here',
  debug: process.env.NODE_ENV === 'development',
  batchSize: 20,
  batchInterval: 5_000,
  offlineQueue: true,
  maxQueueSize: 5_000,
});

// Track an event with BullMQ ingestion hints
analytics.track('user_signup', {
  plan: 'premium',
  source: 'marketing_site',
}, {
  jobName: 'user-onboarding',
  priority: 2,
  attempts: 3,
});

// Identify a user
analytics.identify('user_123', {
  email: 'user@example.com',
  name: 'Ada Lovelace',
  plan: 'premium',
});

// Track page views
analytics.page('Dashboard', {
  category: 'app',
  path: '/dashboard',
});

Offline queueing is enabled by default in this configuration. Events persist to localStorage, flush automatically on visibility change, and fall back to navigator.sendBeacon during page unload, ensuring no analytics are lost for users with intermittent connectivity.

E-commerce Tracking

Track Purchases and Cart Events

typescript

// Track product view
analytics.trackEcommerce({
  action: 'view_item',
  productId: 'SKU-456',
  productName: 'Premium Widget',
  price: 99.99,
  currency: 'USD',
  category: 'Electronics',
});

// Track purchase with queue overrides
analytics.trackEcommerce({
  action: 'purchase',
  orderId: 'order_789',
  revenue: 99.99,
  tax: 8.0,
  shipping: 5.99,
  currency: 'USD',
  products: [
    {
      productId: 'SKU-456',
      quantity: 1,
      price: 99.99,
    },
  ],
}, {
  jobName: 'ecommerce-purchase',
  priority: 1,
});

AI, Voice & Workflows

Capture AI and workflow telemetry

typescript

// Track an AI assistant exchange
analytics.trackAIInteraction({
  role: 'assistant',
  message: 'Here is the summary you asked for...'
}, {
  jobName: 'ai-transcripts',
  attempts: 5,
});

// Collect voice-of-customer feedback
analytics.trackVoiceFeedback({
  transcript: 'The onboarding flow is confusing, can you simplify it?',
  sentiment: 'negative',
  language: 'en-US',
});

// Instrument a workflow journey
analytics.trackWorkflowStep({
  workflowId: 'checkout',
  stepId: 'payment',
  status: 'completed',
  durationMs: 4200,
});

Browser SDK

Installation

bash

npm install insightpro-ai-sdk-browser

React/Next.js Integration

React Hook Integration

typescript

import { useEffect } from 'react';
import InsightPro from 'insightpro-ai-sdk-browser';

// Initialize once (in App.tsx or _app.tsx)
InsightPro.init('your_api_key', {
  apiHost: 'https://your-instance.insightpro-ai.com',
  cookieless: true,
  capturePageViews: true,
  captureClicks: false,
  debug: process.env.NODE_ENV === 'development'
});

// Use in components
function ProductPage({ product }) {
  useEffect(() => {
    InsightPro.track('Product Viewed', {
      product_id: product.id,
      product_name: product.name,
      price: product.price
    });
  }, [product]);

  const handleAddToCart = () => {
    InsightPro.track('Product Added to Cart', {
      product_id: product.id,
      quantity: 1
    });
  };

  return (
    <button onClick={handleAddToCart}>
      Add to Cart
    </button>
  );
}

Vanilla JavaScript

CDN Integration

html

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.insightpro-ai.com/browser/v1/insightpro.min.js"></script>
</head>
<body>
  <script>
    InsightPro.init('your_api_key', {
      apiHost: 'https://your-instance.insightpro-ai.com',
      cookieless: true,
      capturePageViews: true
    });

    // Track button clicks
    document.getElementById('cta-button').addEventListener('click', () => {
      InsightPro.track('CTA Clicked', {
        button_id: 'cta-button',
        page: window.location.pathname
      });
    });
  </script>
</body>
</html>

React Native SDK

Installation

bash

npm install insightpro-ai-sdk-react-native @react-native-async-storage/async-storage

# iOS only
cd ios && pod install

Setup & Usage

Initialize and Track Events

typescript

import InsightPro from 'insightpro-ai-sdk-react-native';

// Initialize the SDK
const analytics = new InsightPro({
  endpoint: 'https://your-instance.insightpro-ai.com',
  tenantId: 'your_tenant_id',
  apiKey: 'your_api_key',
  debug: __DEV__,
  batchSize: 10,
  batchInterval: 5000,
  enableSessions: true
});

// Track screen views
await analytics.trackScreenView('Home Screen', {
  user_type: 'premium'
});

// Track button press
const handlePurchase = async () => {
  await analytics.trackEcommerce({
    action: 'purchase',
    productId: 'product_123',
    productName: 'Premium Plan',
    price: 99.99,
    currency: 'USD'
  });
};

React Navigation Integration

Auto-track Screen Changes

typescript

import { NavigationContainer } from '@react-navigation/native';
import { useRef } from 'react';

export default function App() {
  const routeNameRef = useRef();

  return (
    <NavigationContainer
      onStateChange={async () => {
        const currentRouteName = navigationRef.getCurrentRoute()?.name;

        if (routeNameRef.current !== currentRouteName) {
          await analytics.trackScreenView(currentRouteName);
        }

        routeNameRef.current = currentRouteName;
      }}
    >
      {/* Your navigation */}
    </NavigationContainer>
  );
}

Configuration Options

Option	Type	Default	Description
apiKey	string	required	Your InsightPro API key
apiHost	string	required	Your InsightPro instance URL
tenantId	string	required	Your tenant identifier
debug	boolean	false	Enable debug logging
cookieless	boolean	false	Disable cookie storage (Browser only)
capturePageViews	boolean	true	Auto-track page views (Browser only)
batchSize	number	100	Events to batch before sending
flushInterval	number	10000	Interval to flush events (ms)

Ready to Get Started?

Start building with our enterprise-grade analytics platform today

Start Free Trial Contact Sales