Skip to main content

Working with Fullstory Analytics

Guides and Surveys runs alongside Fullstory Analytics on your site. The two systems each maintain their own user identity and data stores, but they can read from each other in specific ways. This page explains how they relate and when to use each API.

User Identification​

Guides and Surveys and Fullstory Analytics each maintain their own user identifiers:

  • Guides and Surveys user ID: Set on your site with window.USETIFUL.user.setId(userId) or the legacy window.usetifulTags.userId. This value determines how Guides and Surveys persists user progress across sessions and devices.
  • Fullstory user ID: Set on your site with FS('setIdentity', ...). This is the authoritative way to associate a Fullstory session with a user identity in Fullstory Analytics.

On Fullstory instances, the Guides and Surveys script chooses a user identifier for loading and saving progress. If usetifulTags.userId (or an ID set via setId) is present, it takes priority. Otherwise, the script falls back to the Fullstory session ID.

When the session belongs to a user you identified in Fullstory Analytics (FS('setIdentity', ...) was called), Fullstory shares that identity with Guides and Surveys together with user properties that can be used for content targeting. That sync can take up to five minutes.

The two IDs are independent but work together. They can both act as user identifiers for Guides and Surveys Progressor API calls, from different sources.

Important: Do not intentionally use different user IDs in Guides and Surveys and in Fullstory for the same visitor. Doing so creates two distinct user profiles that do not sync data.

Setting a Guides and Surveys user ID explicitly gives persistent, cross-session tracking without waiting for the session ID to be translated to a Fullstory user ID. If you rely only on the Fullstory session ID, progress is session-scoped: each new session is a new identity for Guides and Surveys until Fullstory shares a stable user identity (which can take up to five minutes after FS('setIdentity', ...)).

Tags and Properties​

The two systems also manage their own sets of user metadata:

  • Guides and Surveys tags: window.usetifulTags plus values you set with window.USETIFUL.user.setTag() / setTags(). Tag data is also stored in localStorage under the uf_tags key.
  • Fullstory user properties: Set with the Fullstory Browser API (window.FS(...)). On Fullstory instances, synced user properties used for Guides and Surveys content targeting (for example email, display name, and custom properties) are stored in localStorage under the gs_userProperties key.

Tags and Fullstory user properties are independent. User properties sync between Guides and Surveys and Fullstory Analytics about every five minutes for each user. That sync requires the Guides and Surveys snippet and the Fullstory snippet on the same site, and Data Capture must be enabled.

Both tags and user properties can be used for Guides and Surveys segmentation and targeting. Tags you place in window.usetifulTags are available for targeting immediately; they do not wait on the property sync interval.

When Guides and Surveys resolves tag placeholders (such as {firstName}) in content, it resolves values from both tags and synced user properties. Guides and Surveys reads Fullstory-side identity and properties but does not write user variables back to Fullstory.

Frequently Asked Questions​

Does setting Fullstory user ID or user properties update Guides and Surveys data?​

Partially, yes. The Fullstory session ID is used as the Guides and Surveys temporary user identifier when no Guides and Surveys userId is set. If the session belongs to a user you identified with FS('setIdentity', ...), Fullstory shares that identity with Guides and Surveys, which enables user progress to be loaded and saved through the Progressor API.

On Fullstory instances, the Guides and Surveys script also regularly checks for changes in user properties. Properties used in content targeting are stored in localStorage (gs_userProperties), which makes them available for placeholder replacement and targeting.

Does setting Guides and Surveys user or tag data update Fullstory?​

No. Guides and Surveys sends data to Fullstory in one direction only: it fires FS('trackEvent', ...) for Guides and Surveys lifecycle events such as guide state changes and survey answers. It does not call FS('setIdentity', ...) or set Fullstory user variables.

The relationship is a one-way read (Guides and Surveys reads Fullstory identity and properties) plus a one-way write (Guides and Surveys sends custom events to Fullstory for analytics).

When should I use the Fullstory Browser API?​

Use the Fullstory Browser API (window.FS(...)) when you need to:

  • Identify users in Fullstory with FS('setIdentity', ...), the authoritative way to associate a session with a user identity.
  • Set Fullstory user properties that appear in session recordings and user analytics.
  • Control Fullstory recording behavior (start, stop, consent).

When should I use the Guides and Surveys API?​

Use window.usetifulTags or the Guides and Surveys Browser API (window.USETIFUL) when you need to:

  • Target which Guides and Surveys content a user sees (tours, surveys, banners, checklists). Tags in window.usetifulTags are available for targeting immediately; no sync between Fullstory and Guides and Surveys is required.
  • Trigger content programmatically (for example window.USETIFUL.tour.start(5)).
  • Personalize Guides and Surveys content with dynamic values using tag placeholders such as {firstName}.
  • Debug content targeting (for example window.USETIFUL.tour.getState()).
  • Provide a userId so Guides and Surveys can persist user progress server-side across sessions and devices immediately, without waiting up to five minutes for the session ID to be translated to a Fullstory user ID.
  • Set the Guides and Surveys user ID explicitly. If you rely only on the Fullstory session ID, progress is session-scoped, so a new session means a new identity from the Guides and Surveys perspective.
  • Programmatically control tours, surveys, and checklists.

Setting usetifulTags.userId (or calling setId) takes priority over the Fullstory session ID in Guides and Surveys and gives persistent cross-session user tracking. Without it, Guides and Surveys falls back to the Fullstory session ID.