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

1. 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
   

2. 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.
3. 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();
   

4. 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.

5. 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.