@circuit-ai/react-sdk

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