Skip to main content

Next.js SDK

The @signal-sparrow/next package is a wrapper around the Web SDK, tuned for Next.js. It handles client-side setup for you and automatically tracks navigation between pages.

Setup​

Install the package:

npm install @signal-sparrow/next

Wrap your app with the provider in your root layout. Settings → Tracking generates this snippet for you under Show the provider for your app, with your public key, endpoint and consent mode already filled in:

// app/layout.tsx
import { RevenuePixelProvider } from '@signal-sparrow/next';

export default function RootLayout({
    children,
}: {
    children: React.ReactNode;
}) {
    return (
        <html lang="en">
            <body>
                <RevenuePixelProvider
                    publicKey="pk_live_YOUR_PUBLIC_KEY"
                    endpoint="https://YOUR_TRACKING_DOMAIN/e/YOUR_COLLECT_TOKEN"
                >
                    {children}
                </RevenuePixelProvider>
            </body>
        </html>
    );
}

That's all that's needed for tracking to start — including page views as visitors move around your app.

endpoint is required in a Next.js app

Without it the SDK falls back to the relative path /collect, which points at your own Next.js server rather than Signal Sparrow. Events would be sent and silently dropped. The snippet on Settings → Tracking always includes the correct value.

Provider options​

RevenuePixelProvider accepts the same settings as the Web SDK, passed as props:

<RevenuePixelProvider
    publicKey="pk_live_YOUR_PUBLIC_KEY"
    endpoint="https://YOUR_TRACKING_DOMAIN/e/YOUR_COLLECT_TOKEN"
    consentMode="anonymous"
>
    {children}
</RevenuePixelProvider>
PropTypeRequiredWhat it does
publicKeystringYesYour site's public key (pk_live_…).
endpointstringYes*Where events are sent. See the warning above — without it a Next.js app posts to its own server.
consentMode'anonymous' | 'hold'NoHow the SDK behaves before a visitor consents. Defaults to 'anonymous'.
childrenReactNodeYesYour app. The provider wraps it, so it must not be self-closing.

* Technically optional, but the default (/collect) never works in a Next.js app.

Identifying users​

Use the useIdentify hook inside a client component and call it when a user signs up or logs in:

'use client';

import { useIdentify } from '@signal-sparrow/next';

export function SignupForm() {
    const identify = useIdentify();

    const onSubmit = async (email: string) => {
        // ...create the account
        identify(email);
    };

    return <form>{/* ... */}</form>;
}

This one call is what connects an anonymous visit to a real customer — see Identifying Users.

Custom events​

Need to record an extra front-end action? useRevenuePixel returns track alongside identify and setConsent:

'use client';

import { useRevenuePixel } from '@signal-sparrow/next';

export function DemoButton() {
    const { track } = useRevenuePixel({
        publicKey: 'pk_live_YOUR_PUBLIC_KEY',
        endpoint: 'https://YOUR_TRACKING_DOMAIN/e/YOUR_COLLECT_TOKEN',
    });

    return (
        <button onClick={() => track('Demo Requested')}>Request a demo</button>
    );
}

You can also import track directly from @signal-sparrow/sdk — the provider has already initialised it, so the standalone function works anywhere in your app:

import { track } from '@signal-sparrow/sdk';

track('Demo Requested');
Revenue events are automatic

Subscriptions, upgrades, trial conversions and the like come from Stripe, so you don't need to fire those yourself.

Next​