How to Programmatically Start a Product Tour

This guide shows you how to start a Userorbit product tour programmatically using JavaScript, so you can trigger tours based on user interactions instead of relying solely on automatic targeting.

Before You Begin

The Userorbit SDK is installed and initialized in your application.
At least one product tour is published in your Userorbit Admin Panel.
The tour ID, which you can find in the Product Tours section of the admin panel.

API Method

await userorbit.startTour(tourId);

Parameter	Type	Description
`tourId`	`string`	The ID of the published tour to start

The method returns a Promise that resolves once the tour begins rendering. If the tour is not found (e.g., it hasn't been published or the SDK isn't initialized), a warning is logged to the console.

Examples

Trigger a tour on button click

document.getElementById("start-tour-button").addEventListener("click", () => {
  userorbit.startTour("your-tour-id");
});

Trigger a tour in React

import userorbit from "userorbit-js";

function OnboardingButton() {
  const handleClick = () => {
    userorbit.startTour("your-tour-id");
  };

  return <button onClick={handleClick}>Start Tour</button>;
}

Trigger a tour after form submission

document.getElementById("save-settings-form").addEventListener("submit", (event) => {
  event.preventDefault();
  // Save settings logic...
  userorbit.startTour("your-tour-id");
});

Conditional triggering based on user state

if (currentUser.isNewUser && !currentUser.hasCompletedOnboarding) {
  userorbit.startTour("your-onboarding-tour-id");
}

The SDK also provides similar methods for starting surveys and checklists programmatically:

// Start a survey by ID
await userorbit.startSurvey("your-survey-id");

// Start a checklist by ID
await userorbit.startChecklist("your-checklist-id");

Checklist Integration

You can also configure checklist items in the admin panel to start a tour automatically when the item is triggered — no custom code required.

Troubleshooting

Tour not appearing? Make sure userorbit.init() has been called and the tour is published in the admin panel.
Console warning "Tour with id not found"? Double-check the tour ID and confirm the tour is published, not in draft.
Tour has a delay? If the tour is configured with a display delay in the admin panel, it will wait that many seconds before rendering.

Help Center