Installation

Before You Start

You'll need:

A SupaStory account — Sign up free
A web app (React, Next.js, Vue, or plain JavaScript all work)

That's it. Let's go.

Install the Package

Open your terminal and run:

npm install @supastory/capture-sdk

Using yarn or pnpm? Those work too:

yarn add @supastory/capture-sdk
# or
pnpm add @supastory/capture-sdk

Add the SDK to Your App

Copy this code and add it to your app's main file. You'll need your Project Key from the SupaStory dashboard — find it in Settings > Project. It looks like pk_live_....

Add this to your App.jsx (or App.tsx):

import { useEffect } from 'react';
import { SupaStory } from '@supastory/capture-sdk';

function App() {
  useEffect(() => {
    SupaStory.init({
      projectKey: 'pk_live_...', // Your project key from the dashboard
    });
  }, []);

  return <YourApp />;
}

Add this to your root layout file (app/layout.tsx):

'use client';

import { useEffect } from 'react';
import { SupaStory } from '@supastory/capture-sdk';

export default function RootLayout({ children }) {
  useEffect(() => {
    SupaStory.init({
      projectKey: 'pk_live_...', // Your project key from the dashboard
    });
  }, []);

  return (
    <html>
      <body>{children}</body>
    </html>
  );
}

Add this to your main.js:

import { createApp } from 'vue';
import { SupaStory } from '@supastory/capture-sdk';
import App from './App.vue';

// Initialize SupaStory before mounting
SupaStory.init({
  projectKey: 'pk_live_...', // Your project key from the dashboard
});

createApp(App).mount('#app');

Add this script to your HTML, or import it in your JS entry file:

<script type="module">
  import { SupaStory } from '@supastory/capture-sdk';

  SupaStory.init({
    projectKey: 'pk_live_...', // Your project key from the dashboard
  });
</script>

Configuration Options

The defaults work for most apps, but here are some useful options you can pass to init():

SupaStory.init({
  projectKey: 'pk_live_...',

  // Record only a percentage of sessions (default: 1.0 = 100%)
  samplingRate: 0.5,

  // Set to false for consent flows (default: true)
  autoStart: false,

  // Maximum session length in minutes (default: 60)
  maxSessionDuration: 30,

  // How often to send captured events, in milliseconds (default: 5000)
  batchInterval: 3000,
});

Sampling is useful for high-traffic sites where you don't need every session. Set it to 0.5 to record half of sessions, 0.1 for 10%, and so on.

Manual start is great for consent flows. Set autoStart: false, then call SupaStory.start() after the user agrees. See Privacy Controls for more.

Controlling Recording

Once initialized, you can control recording at any time:

SupaStory.start();    // Start recording (if autoStart is false)
SupaStory.stop();     // Stop recording completely
SupaStory.pause();    // Pause temporarily
SupaStory.resume();   // Resume after pausing

// Useful for debugging
const status = SupaStory.getStatus();     // 'recording' | 'paused' | 'stopped' | 'idle'
const sessionId = SupaStory.getSessionId(); // Current session ID, or null

Check It's Working

Start your app locally
Click around a bit—fill out a form, navigate between pages
Open your SupaStory dashboard
You should see your session appear within a minute or two

That's it. SupaStory is now recording sessions and the AI will start analyzing them automatically.

Optional: Connect GitHub

Want SupaStory to automatically create pull requests with bug fixes? Connect your GitHub repo:

Go to Settings > Integrations in your dashboard
Click Connect GitHub
Pick the repository for your project
Done—fixes will now appear as PRs

What's Next?

Core Concepts — Understand how the AI analysis works
Privacy Controls — Configure what gets recorded
Conversion Tracking — Measure the impact of fixes

Common Questions

Does this slow down my site? No. The capture SDK is tiny (~9KB gzipped) and loads asynchronously. Users won't notice any difference.

What if I'm using a different framework? The capture SDK works with any JavaScript environment. Just call SupaStory.init() once when your app loads.

Can I test locally? Yes! Sessions recorded on localhost will show up in your dashboard too.

On this page