Install userorbit-js once at the authenticated React app-shell boundary, then identify the signed-in person after authentication is ready. For B2B applications, pass the active account as stable custom attributes so tours, checklists, and events can target the correct tenant.

Before you begin

You need:

  • a React web application with an authenticated-user boundary
  • the public Account ID from Userorbit → Settings → Widget
  • a stable application user ID and, for B2B applications, a stable account or workspace ID
  • a staging user and route for verification
  • a published tour or checklist if you want to test in-app delivery

The Account ID is safe to expose in browser code. API keys, access tokens, signing secrets, and private customer data must remain on the server.

1. Install the web SDK

Use the package manager already used by your application:

npm install userorbit-js
Bash
pnpm add userorbit-js
Bash

When init() runs, the package loads the browser runtime from https://cdn.userorbit.com/userorbit.umd.cjs. If your application uses a Content Security Policy, allow the Userorbit CDN in script-src and the API host shown in your generated setup in connect-src.

2. Initialize Userorbit once

Keep initialization in a component that remains mounted for the authenticated application shell. A module-level promise prevents React Strict Mode's development remount from starting a second initialization while the first one is still running.

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

const accountId = import.meta.env.VITE_USERORBIT_ACCOUNT_ID

let sdkReady: Promise<void> | undefined

function ensureUserorbit() {
  if (!accountId) {
    return Promise.reject(new Error("Missing VITE_USERORBIT_ACCOUNT_ID"))
  }

  sdkReady ??= userorbit.init({
    accountId,
    apiHost: "https://api.userorbit.com",
    floatingWidget: true,
  })

  return sdkReady
}
TSX

This example uses Vite's client environment-variable convention. Use the equivalent public configuration mechanism if your application uses another bundler. Always compare the example with the generated setup in Settings → Widget before deployment.

3. Identify the signed-in person and active account

Call identify() after your authentication provider has resolved the current user:

type UserorbitUser = {
  id: string
  email?: string
  name?: string
  role?: string
  account: {
    id: string
    name?: string
    plan?: string
  }
}

export function UserorbitProvider({ user }: { user: UserorbitUser }) {
  useEffect(() => {
    let current = true

    async function syncIdentity() {
      await ensureUserorbit()
      if (!current) return

      await userorbit.identify(user.id, {
        email: user.email,
        name: user.name,
        attributes: {
          "user.role": user.role,
          "account.id": user.account.id,
          "account.name": user.account.name,
          "account.plan": user.account.plan,
        },
      })
    }

    void syncIdentity()

    return () => {
      current = false
    }
  }, [
    user.id,
    user.email,
    user.name,
    user.role,
    user.account.id,
    user.account.name,
    user.account.plan,
  ])

  return null
}
TSX

Render <UserorbitProvider user={currentUser} /> after authentication is ready.

The current web SDK identifies a person. It does not expose a separate company or group identification method. In a multi-tenant B2B application, use stable custom attributes such as account.id, account.name, account.plan, and user.role to describe the active tenant and role.

Use opaque application IDs. Send email and name only when your privacy basis and consent flow permit them.

If a person switches accounts without signing out, call identify() again with the new account.* values. When the application signs out, clear the Userorbit session from the same sign-out path:

await userorbit.logout()
sdkReady = undefined
TypeScript

4. Configure and launch a tour or checklist

Create and publish the experience in Userorbit before calling it from application code. Configure its URL, audience, frequency, and schedule for a staging user first.

To start a published tour from a button:

export function StartWorkspaceTourButton() {
  async function startTour() {
    await ensureUserorbit()
    await userorbit.startTour("YOUR_PUBLISHED_TOUR_ID")
  }

  return <button onClick={startTour}>Show me how</button>
}
TSX

To start a published checklist:

await ensureUserorbit()
await userorbit.startChecklist("YOUR_PUBLISHED_CHECKLIST_ID")
TypeScript

These methods do not create or publish an experience. They request a published tour or checklist that is available to the current user. If the ID is wrong, the experience is still a draft, or the current user is not eligible, inspect the browser console and the experience's targeting rules.

5. Track a configured product event

Create the code event in Userorbit first, then call its exact key only after the product action succeeds:

await userorbit.track("workspace_created", {
  hiddenFields: {
    workspaceId: workspace.id,
    template: workspace.templateKey,
  },
})
TypeScript

Keep event payloads small. hiddenFields values can be strings, numbers, or arrays of strings. Do not send credentials, message bodies, or arbitrary customer records.

Userorbit owns the event-to-experience or event-to-checklist-task configuration. Your application owns firing the event at the correct success boundary.

6. Handle client-side route changes

The SDK detects common History API, popstate, and hash changes. Do not add a manual route hook until verification shows a missed navigation.

If an experience does not re-evaluate after a real client-side navigation, call:

await userorbit.registerRouteChange()
TypeScript

Place the call in an effect keyed to your router's current location, then recheck Live Events. If one navigation produces two page-view events, remove the fallback because automatic detection already covers your router.

7. Verify the complete path

Verify each layer independently:

Layer Test Passing evidence
Runtime Reload the staging application with DevTools open userorbit.umd.cjs loads without a CSP or network error
SDK connection Open Settings → Widget The workspace reports recent SDK activity
Environment Open Analytics → Live Events A recent $uo_web_page_view has the intended staging URL
Identity Open the staging contact The stable user ID and expected account.* attributes are present
Targeting Test one eligible and one ineligible user Only the eligible user receives the experience
Delivery Start the published tour or checklist on its real route The first step attaches to the intended element
Outcome Complete and dismiss separate test runs The experience records the corresponding progress state
Product event Complete the real application action The configured experience or checklist task responds once

Do not treat a growing Contacts count as installation proof; contacts can also arrive through imports or APIs.

Troubleshooting

The SDK does not load

  • Confirm that the Account ID came from the workspace you are testing.
  • Check script-src for https://cdn.userorbit.com and connect-src for the configured API host.
  • Look for an ad blocker or privacy extension blocking a request.
  • Confirm that the provider is mounted in a browser-rendered React tree.

The wrong person or account receives onboarding

  • Use an immutable application user ID instead of email as the primary ID.
  • Confirm that account.id changes when the person switches tenants.
  • Call logout() when the application signs out.
  • Match attribute keys exactly; account.plan and plan are different keys.

A tour or checklist is not found

  • Confirm that the experience is published.
  • Copy the ID again from the same workspace.
  • Check URL, audience, frequency, schedule, and previous completion or dismissal state.
  • Wait until the target element exists before starting a pointer step.

A product event does nothing

  • Create the code event in Userorbit before calling track().
  • Match the event key exactly, including case.
  • Fire after the product action succeeds, not when its button is merely clicked.
  • Keep hiddenFields within the supported value types.

Implementation ownership

Userorbit provides the browser SDK, person identity, custom attributes, configured events, targeting, tours, checklists, Live Events, and delivery analytics. Your application owns authentication readiness, stable IDs, tenant switching, consent, CSP, event correctness, and regression testing after UI changes.

For Next.js-specific placement, see How to Install the Userorbit SDK in Next.js. For additional failure modes, see SDK Troubleshooting Reference in the help center.

Was this helpful?