Installation Guide

The FeedSense feedback widget takes just 2 minutes to install. Choose the method that fits your stack.

Step 1: Get Your API Key

Log in to your FeedSense dashboard
Navigate to Settings → API
Click Generate API Key
Copy the key immediately — it is only shown once

Step 2: Install the Widget

Option A: npm (React / Next.js)

Install the SDK package:

npm install @feedsense/sdk

Initialize the SDK in your app:

import FeedSenseSDK from '@feedsense/sdk';

await FeedSenseSDK.init({
  apiKey: 'your-api-key',
  apiUrl: 'https://api.feedsense.co'
});

Next.js with FeedSenseProvider

For Next.js apps, create a provider component that wraps your layout. This is how the FeedSense landing site itself integrates the widget:

// components/providers/FeedSenseProvider.tsx
'use client';

import { useEffect, useRef } from 'react';

interface FeedSenseProviderProps {
  apiKey: string;
  apiUrl?: string;
  children: React.ReactNode;
}

export function FeedSenseProvider({
  apiKey,
  apiUrl,
  children
}: FeedSenseProviderProps) {
  const isInitialized = useRef(false);

  useEffect(() => {
    if (isInitialized.current || !apiKey) return;

    let destroyed = false;

    const initWidget = async () => {
      try {
        const FeedSenseSDK = await import('@feedsense/sdk');
        if (destroyed) return;

        await FeedSenseSDK.default.init({
          apiKey,
          ...(apiUrl && { apiUrl }),
        });

        if (!destroyed) {
          isInitialized.current = true;
        }
      } catch (error) {
        console.error('[FeedSense] Failed to initialize:', error);
      }
    };

    initWidget();

    return () => {
      destroyed = true;
    };
  }, [apiKey, apiUrl]);

  return <>{children}</>;
}

Then wrap your app in app/layout.tsx:

// app/layout.tsx
import { FeedSenseProvider } from '@/components/providers/FeedSenseProvider';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <FeedSenseProvider
          apiKey={process.env.NEXT_PUBLIC_FEEDSENSE_API_KEY || ''}
          apiUrl={process.env.NEXT_PUBLIC_FEEDSENSE_API_URL}
        >
          {children}
        </FeedSenseProvider>
      </body>
    </html>
  );
}

Programmatic Control with useFeedSense Hook

You can open and close the widget programmatically using a custom hook:

// hooks/useFeedSense.ts
'use client';

import { useCallback, useState, useEffect, useRef } from 'react';

export function useFeedSense() {
  const [isAvailable, setIsAvailable] = useState(false);
  const sdkRef = useRef<typeof import('@feedsense/sdk') | null>(null);

  useEffect(() => {
    let cancelled = false;

    const loadAndCheck = async () => {
      try {
        const FeedSenseSDK = await import('@feedsense/sdk');
        sdkRef.current = FeedSenseSDK;
        if (!cancelled) setIsAvailable(FeedSenseSDK.isInitialized());
      } catch {
        if (!cancelled) setIsAvailable(false);
      }
    };

    loadAndCheck();

    const interval = setInterval(() => {
      if (sdkRef.current) {
        const ready = sdkRef.current.isInitialized();
        if (!cancelled) setIsAvailable(ready);
        if (ready) clearInterval(interval);
      }
    }, 1000);

    return () => {
      cancelled = true;
      clearInterval(interval);
    };
  }, []);

  const open = useCallback(async () => {
    const sdk = sdkRef.current ?? await import('@feedsense/sdk');
    if (sdk.isInitialized()) sdk.open();
  }, []);

  const close = useCallback(async () => {
    const sdk = sdkRef.current ?? await import('@feedsense/sdk');
    if (sdk.isInitialized()) sdk.close();
  }, []);

  return { open, close, isAvailable };
}

Use it in any component:

const { open, isAvailable } = useFeedSense();

return (
  <button onClick={open} disabled={!isAvailable}>
    Send Feedback
  </button>
);

Option B: Script Tag (Plain HTML)

Add this snippet before the closing </body> tag:

<script src="https://unpkg.com/@feedsense/sdk@latest/dist/index.umd.js"></script>
<script>
  FeedSenseSDK.init({
    apiKey: 'your-api-key',
    apiUrl: 'https://api.feedsense.co'
  });
</script>

Step 3: Verify Installation

Visit your website
Look for the feedback tab on the right side of the page
Click it to test the feedback form
You should see test feedback appear in your dashboard within seconds

Configuration Options

The basic setup only requires apiKey. The following options are available:

Option	Type	Default	Description
`apiKey`	string	—	Your FeedSense API key (required)
`apiUrl`	string	`https://api.feedsense.co`	API endpoint URL
`onSubmit`	function	—	Callback invoked after successful feedback submission
`onError`	function	—	Callback invoked when submission fails (falls back to alert if not provided)

Example with callbacks:

FeedSenseSDK.init({
  apiKey: 'your-api-key',
  apiUrl: 'https://api.feedsense.co',
  onSubmit: (feedback) => {
    console.log('Feedback submitted:', feedback);
  },
  onError: (error) => {
    console.error('Submission failed:', error);
  },
});

Troubleshooting

Widget not appearing?

Check that your API key is correct and has been generated in Settings → API
For script tag: ensure the script is before the closing </body> tag
For npm: make sure the SDK is initialized before rendering
Clear your browser cache and refresh
Check browser console for errors