Skip to main content

​
Developer Docs

Run Userorbit widget and show announcements, roadmap, feedback and tours inside your Web Apps and Websites

​
Overview

The Userorbit JS SDK is a versatile solution for integrating tours into both web apps and websites. It adapts based on the presence of a userId. If a userId is provided, the SDK handles authenticated tours for logged-in users in web apps. If no userId is provided, the SDK can still seamlessly run tours on public-facing websites. The SDK is available on npm here.

​
Install

  npm install userorbit-js

​
Methods

​
Initialize Userorbit

Initialize the Userorbit JS Client - When used in a web app, pass a userId to create and target a specific user. When using it on a website without authentication, simply omit the userId.
Initialize Userorbit
import userorbit from "userorbit-js";

userorbit.init({
  accountId: "<account-id>", // required
  apiHost: "<your-api-host>", // optional, defaults to "https://api.userorbit.com"
  userId: "<user-id>", // optional
  email: "<user-email>", // optional
  name: "<user-name>", // optional
  attributes: { // optional
    plan: "paid",
    role: "admin"
  },
  theme: "light" | "dark", // optional
  widget: { // optional
    theme: "light" | "dark"
  },
  analytics: { // optional
    enabled: true
  },
  floatingWidget: true, // optional
  widgetMountSelector: "<css-selector>", // optional
  errorHandler: (error) => { // optional
    console.error("Userorbit error:", error);
  }
});
Userorbit JS is a client SDK meant to be run client-side in their browser so make sure the window object is accessible. Below is an example of how you can set it!
if (typeof window !== "undefined") {
  userorbit.init({
    accountId: "<account-id>",
    apiHost: "<your-api-host>", // optional
    userId: "<user-id>", //optional
  });
} else {
  console.error("Window object not accessible to init Userorbit");
}

​
Set Attribute

Set custom attributes for the identified user to help segment them based on specific attribues. 
userorbit.setAttribute("plan", "paid");

​
Set Email

Update the email address of the currently identified user. 
userorbit.setEmail("[email protected]");

​
Track Action

Track user actions to trigger tours based on user interactions, such as button clicks or scrolling. You can also pass optional properties like hiddenFields. 
userorbit.track("Clicked on Plans", {
  hiddenFields: {
    source: "header"
  }
});

​
Logout

To log out and deinitialize Userorbit, use the userorbit.logout() function. This action clears the current initialization configuration and erases stored frontend information, such as the tours a user has viewed or completed. It’s an important step when a user logs out of your application or when you want to reset Userorbit. 
userorbit.logout();
After calling userorbit.logout(), you’ll need to reinitialize Userorbit before using any of its features again. Ensure that you properly reinitialize Userorbit to avoid unexpected errors or behavior in your application.

​
Reset

Reset the current instance and fetch the latest tours and state again: 
userorbit.reset();

​
Register Route Change:

Listen for page changes and dynamically show tours configured via no-code actions in the Userorbit app: 
userorbit.registerRouteChange();
This is only needed when your framework has a custom routing system and you want to trigger tours on route changes. For example: NextJsRefer to the Framework Guides for more information.

​
Update Theme

Change the widget theme dynamically between light and dark mode. 
userorbit.updateTheme("dark");

​
Open Widget

Programmatically open the Userorbit widget. You can optionally specify which tab to open or target a specific item. 
userorbit.openWidget({
  tab: "feedback", // "feedback" | "roadmap" | "updates" | "help"
  showFeedbackForm: true
});

​
OpenWidgetOptions

PropertyTypeDescription
tabstringThe tab to open: "feedback", "roadmap", "updates", or "help".
announcementIdstringOpen a specific announcement.
roadmapIdstringOpen a specific roadmap.
topicIdstringOpen a specific topic.
articleIdstringOpen a specific help article.
showFeedbackFormbooleanWhether to directly show the feedback submission form.
modalbooleanWhether to open as a modal.
compactbooleanWhether to use a compact layout.
positionstringPosition of the widget: "bottom-right", "bottom-left", or "top-right".

​
Start Survey

Programmatically trigger a survey by its ID. 
userorbit.startSurvey("survey-id");

​
Start Tour

Programmatically trigger a tour by its ID. 
userorbit.startTour("tour-id");

​
Start Checklist

Programmatically trigger a checklist by its ID. 
userorbit.startChecklist("checklist-id");

​
Get API

Retrieve the underlying API client for making custom calls to Userorbit. 
const api = userorbit.getApi();
const response = await api("/some-endpoint", { data: "..." });

​
Trigger Survey

Manually trigger a survey with a full survey object. This is typically used for previews. 
userorbit.triggerSurvey({
  survey: surveyData,
  account: "account-id",
  // ... other SurveyPreviewProps
});

​
Debug Mode

To enable debug mode in Userorbit, add ?userorbitDebug=true to your app’s URL. For example, if you’ve integrated Userorbit JS to your app hosted at https://example.com, then change the URL to https://example.com?userorbitDebug=true and refresh the page, now view the console logs to see the debug mode live in action. This activates detailed debug messages in the browser console, providing deeper insights into Userorbit’ operation and potential issues.

​
Troubleshooting

In case you don’t see your tour right away, here’s what you can do. Go through these to find the error fast:

​
Tour not triggered

If the tour is loaded by the widget it might not have been triggered properly. How to fix:
  1. Open your local app in an incognito tab or window. The New Session event is only fired if a user was inactive for 60 minutes or was logged out of Userorbit via userorbit.logout().
  2. Check the debug logs for “Event ‘New Session” tracked”. If you see it in the logs and the tour still did not get displayed, please let us know.

​
Tour not displayed in HTML page

If the tour is loaded by the widget in the HTML page, try the below steps: How to fix:
  1. Make sure you have added the script in the head of the HTML page.
  2. Verify that you have set the <account-id> as per your Userorbit instance.
  3. Verify that you have the latest version of the JS Package.
  4. Check the debug logs to see if you still see any errors.

​
Cannot read undefined of .init()

If you see this error in the console, it means that the Userorbit JS package is not loaded properly. How to fix:
  1. Update to the latest version of the JS Package.
  2. Verify this wherever you call initialise the Userorbit instance in your code.
  3. It should now start working.

​
Multi-page tours not working in SPAs (Next.js, etc.)

A common issue in Single Page Applications (SPAs) and hybrid frameworks like Next.js is that multi-page product tours may not automatically progress when the route changes. This occurs because these frameworks use internal routing that might not register with Userorbit’s default listeners. How to fix: To fix this, you must manually call userorbit.registerRouteChange() whenever your application’s route changes. This ensures Userorbit is aware of the new path and can trigger the appropriate tour steps. 
userorbit.registerRouteChange();
Refer to the Framework Guides for specific implementation examples for Next.js, React, and Vue.