Circuit SDK for Next.js

A powerful SDK for tracking user sessions, interactions, and API calls in Next.js applications.

Features

• User session tracking
• Click event tracking with element paths
• API call interception (both fetch and axios)
• Tab visibility tracking
• Automatic event batching and sending
• TypeScript support

Installation

npm install circuit-sdk
# or
yarn add circuit-sdk

Usage

Basic Setup

// In your _app.tsx or similar entry point
import { useCircuit } from "circuit-sdk";

function MyApp({ Component, pageProps }) {
  useCircuit({
    apiKey: "your-api-key",
    debug: true, // Optional, enables console logging
  });

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

export default MyApp;

Manual Initialization

If you need more control over the Circuit instance:

import { initCircuit } from "circuit-sdk";

const circuit = initCircuit({
  apiKey: "your-api-key",
});

Events

The SDK automatically tracks:

1. Session Events

   • Session start/end
   • Includes unique session ID

2. Click Events

   • Coordinates (x, y)
   • Target element
   • Element path in DOM

3. API Calls

   • URL
   • Method
   • Status
   • Error information (if any)

4. Tab Visibility

   • Tracks when user switches tabs
   • Records timestamps for video pause points

Event Format

Events are automatically sent to Circuit's servers in the following format:

{
  sessionId: string;
  events: Array<{
    type:
      | "click"
      | "api_call"
      | "tab_visibility"
      | "session_start"
      | "session_end";
    timestamp: number;
    data: {
      // Varies based on event type
    };
  }>;
}

Configuration Options

| Option | Type | Required | Description | | ------ | ------- | -------- | -------------------------------- | | apiKey | string | Yes | Your Circuit API key | | debug | boolean | No | Enable console logging of events |

Best Practices

1. Initialize the SDK as early as possible in your application
2. Use the useCircuit hook in your top-level component
3. Enable debug mode during development

License

MIT