How to Install the Userorbit SDK in Next.js

This guide shows you how to integrate the Userorbit SDK into your Next.js application, covering both the App Router (Next.js 13+) and Pages Router.

Before You Begin

A working Next.js application.
Node.js and npm/yarn/pnpm installed.
Your Userorbit Account ID from the Userorbit Admin Panel (Settings → Widget).

Steps

Install the Userorbit SDK package

// npm
npm install userorbit-js

// yarn
yarn add userorbit-js

// pnpm
pnpm add userorbit-js

App Router: Create a client component for initialization — Since the Userorbit SDK runs in the browser, it must be initialized inside a Client Component with a typeof window guard.

Create components/userorbit.tsx:

"use client";

import { useEffect } from "react";
import userorbit from "userorbit-js";

export function UserorbitInit() {
  useEffect(() => {
    if (typeof window !== "undefined") {
      userorbit.init({
        accountId: "YOUR_ACCOUNT_ID",
      });
    }
  }, []);

  return null;
}

Then add it to your root layout in app/layout.tsx:

import { UserorbitInit } from "@/components/userorbit";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <UserorbitInit />
        {children}
      </body>
    </html>
  );
}

Pages Router: Initialize in _app.tsx — If you are using the Pages Router, initialize the SDK in your custom App component.

import type { AppProps } from "next/app";
import { useEffect } from "react";
import userorbit from "userorbit-js";

export default function MyApp({ Component, pageProps }: AppProps) {
  useEffect(() => {
    if (typeof window !== "undefined") {
      userorbit.init({
        accountId: "YOUR_ACCOUNT_ID",
      });
    }
  }, []);

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

Identify users after authentication — To associate actions with a logged-in user, pass their details in the init config.

App Router example — update components/userorbit.tsx:

"use client";

import { useEffect } from "react";
import userorbit from "userorbit-js";
import { useSession } from "next-auth/react"; // or your auth provider

export function UserorbitInit() {
  const { data: session } = useSession();

  useEffect(() => {
    if (typeof window !== "undefined" && session?.user) {
      userorbit.init({
        accountId: "YOUR_ACCOUNT_ID",
        userId: session.user.id,
        email: session.user.email,
        name: session.user.name,
        attributes: {
          plan: session.user.plan,
        },
      });
    }
  }, [session]);

  return null;
}

You can also update user attributes after initialization:

await userorbit.setEmail("new@example.com");
await userorbit.setAttribute("plan", "enterprise");
await userorbit.track("feature-used", {
  hiddenFields: { feature: "analytics" },
});
await userorbit.logout();

Register route changes — The Userorbit SDK automatically detects Next.js route changes for both App Router and Pages Router, so no manual registerRouteChange() call is needed in most cases. If you find that page-targeted tours or surveys are not triggering on navigation, you can add a manual fallback:

App Router:

"use client";

import { useEffect } from "react";
import { usePathname } from "next/navigation";
import userorbit from "userorbit-js";

export function RouteChangeTracker() {
  const pathname = usePathname();

  useEffect(() => {
    userorbit.registerRouteChange();
  }, [pathname]);

  return null;
}

Pages Router:

import { useEffect } from "react";
import { useRouter } from "next/router";
import userorbit from "userorbit-js";

export function RouteChangeTracker() {
  const router = useRouter();

  useEffect(() => {
    const handleRouteChange = () => {
      userorbit.registerRouteChange();
    };
    router.events.on("routeChangeComplete", handleRouteChange);
    return () => {
      router.events.off("routeChangeComplete", handleRouteChange);
    };
  }, [router]);

  return null;
}

Verify the installation — Start your application with npm run dev and check your browser developer tools.
- In the Network tab, filter for requests to the Userorbit API.
- In the Console, type window.userorbit and press Enter — it should return the SDK object.
- Check your Userorbit Admin Panel for incoming data.

Important Notes

SSR safety: Always wrap userorbit.init() in a typeof window !== "undefined" check or inside a useEffect hook. The SDK requires the browser DOM and will not work during server-side rendering.
App Router: Any component that uses the Userorbit SDK must have the "use client" directive at the top of the file.
Environment variables: Store your Account ID in NEXT_PUBLIC_USERORBIT_ACCOUNT_ID so it is available on the client side. Next.js only exposes environment variables prefixed with NEXT_PUBLIC_ to the browser.

Init Configuration Reference

The init method accepts a configuration object with the following properties:

Property	Type	Required	Description
`accountId`	`string`	Yes	Your Userorbit Account ID
`userId`	`string`	No	Unique identifier for the current user
`email`	`string`	No	User email address
`name`	`string`	No	User display name
`attributes`	`Record<string, string>`	No	Custom user attributes for segmentation
`theme`	`"light" \| "dark"`	No	Widget color theme
`floatingWidget`	`boolean`	No	Show the floating widget button

Help Center