Skip to main content

Getting Started

The Guides and Surveys Browser API provides programmatic access to Guides and Surveys functionality on your website. Use it to identify users, control tours and checklists, manage surveys, and personalize content based on user data.

About the API Object​

The Guides and Surveys Browser API is accessed through the window.USETIFUL object. Although the product is called "Guides and Surveys," the JavaScript API retains the USETIFUL name. All API methods are called on this object — for example, window.USETIFUL.user.setId('user123').

Requirements​

To use the Guides and Surveys Browser API, your environment must meet the following requirements:

  • Guides and Surveys add-on: Your Fullstory plan must include the Guides and Surveys add-on, available on Business, Advanced, and Enterprise plans.
  • Installation: Guides and Surveys must be installed on your site. See the installation guide for setup instructions.
  • gs.js script: The gs.js script must be loaded on the page before calling any API methods. Use initialization events to detect when the API is ready.

Initialization​

Before calling API methods, listen for initialization events to ensure the script has loaded:

document.addEventListener('usetiful:basicApiReady', () => {
  window.USETIFUL.user.setId('user123');
});

document.addEventListener('usetiful:fullApiReady', () => {
  // All APIs are ready, including user progress data
});

The usetiful:basicApiReady event fires when the script has loaded and user methods (setId, setTag, setTags) are available. The usetiful:fullApiReady event fires when all APIs are ready and user progress has been loaded.

API Sections​

  • Initialization Events — Detect when the API is ready to use
  • Script Lifecycle — Reinitialize triggers, remove content, and deactivate the script
  • User — Set user identity and tags, manage user progress
  • Tour — Start, navigate, and control tours
  • Checklist — Open checklists and mark items complete
  • Surveys — Display surveys, navigate pages, and manage completion state

Working with Fullstory Analytics​

Guides and Surveys runs alongside Fullstory Analytics on your site but maintains its own user data and identity system. To understand how the two systems interact and when to use each API, see Working with Fullstory Analytics.