How to Install the Userorbit SDK in a React Application

This guide shows you how to integrate the Userorbit SDK into your React application, enabling user engagement, analytics, and AI-powered tools.

Before You Begin

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

Steps

Install the Userorbit SDK package — Use your preferred package manager to add the Userorbit SDK to your project.
```
// npm
npm install userorbit-js

// yarn
yarn add userorbit-js

// pnpm
pnpm add userorbit-js
```
Initialize the SDK in your main App component — Add the initialization script within a useEffect hook in your root App component or main layout to ensure it runs once when the component mounts.
```
import { useEffect } from "react";
import userorbit from "userorbit-js";

function App() {
  useEffect(() => {
    userorbit.init({
      accountId: "YOUR_ACCOUNT_ID",
    });
  }, []);

  return <div>...</div>;
}

export default App;
```
Note: Replace "YOUR_ACCOUNT_ID" with your actual Account ID from the Userorbit Admin Panel.

Identify users after authentication — To associate actions with a specific user, pass their details in the init config. This example demonstrates integration with a hypothetical authentication context.

import { useEffect, useContext } from "react";
import userorbit from "userorbit-js";
import { AuthContext } from "./AuthContext";

function App() {
  const { user, isAuthenticated } = useContext(AuthContext);

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

  return <div>...</div>;
}

export default App;

You can also update user attributes after initialization:

// Set the user email
await userorbit.setEmail("new@example.com");

// Set a custom attribute
await userorbit.setAttribute("plan", "enterprise");

// Track a custom event
await userorbit.track("feature-used", {
  hiddenFields: { feature: "analytics" },
});

// Log the user out
await userorbit.logout();

Register route changes — Since React uses client-side routing, the SDK needs to be notified when the user navigates to a new page. Call registerRouteChange() on every route change so that page-targeted tours, surveys, and checklists can trigger correctly.
```
import { useEffect } from "react";
import { useLocation } from "react-router-dom";
import userorbit from "userorbit-js";

function RouteChangeTracker() {
  const location = useLocation();

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

  return null;
}
```
Render <RouteChangeTracker /> inside your <Router> so it picks up every navigation.
Verify the installation — After running your application, check your browser developer tools to confirm the SDK is working.
- Open your browser developer tools (usually F12).
- Navigate to the "Network" tab and filter for requests to the Userorbit API.
- Check the "Console" tab for initialization messages or errors.
- In the console, type window.userorbit and press Enter; it should return the SDK object.

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

Note on React Strict Mode: During development, React Strict Mode might cause components to mount, unmount, and re-mount immediately. The Userorbit SDK is designed to handle this gracefully, and double-mounting in development will not cause issues in production.

For Next.js Applications: If you are using Next.js, there is a dedicated guide available that covers specific integration patterns for server-side rendering (SSR) and static site generation (SSG). Refer to the Userorbit SDK in Next.js article for more details.

Help Center