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 either by defining window.usetifulTags = { userId: "your_id" } before the script loads, or by calling window.USETIFUL.user.setId(userId) after it has loaded. Both approaches are equivalent—the difference is only in timing. 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, Guides and Surveys reaches these through two independent paths—see below.

Fullstory User Properties​

Fullstory user properties reach Guides and Surveys through two independent paths:

  • In-session (immediate): Properties set with FS('setProperties', {type: 'user', ...}) or FS('setIdentity', ...) in the current browser session are observed live by the Guides and Surveys script and stored in localStorage under the gs_fsUser key. This path is not limited to properties used in targeting rules, and it overrides any stale synced values for the same property. Because it's observed live, it's the path to use when a property needs to be available immediately—for example, on every page load—for placeholder substitution or targeting.
  • Backend sync (~5 minutes): Server-only properties—for example those set through the Server API, set before identity is established, or accumulated/segment data—sync from Fullstory Analytics to Guides and Surveys roughly every five minutes and are stored in localStorage under the gs_userProperties key. That sync requires the Guides and Surveys snippet and the Fullstory snippet on the same site, and Data Capture must be enabled. Only properties referenced in a targeting rule are included in this sync. Reserved properties displayName and email are never delivered through this sync path—they're only available through the in-session path above, so to target or personalize on them you must set them in the browser (before content loads) rather than relying on the backend sync.

Guides and Surveys merges both localStorage sources when it needs a property's value, and the in-session (gs_fsUser) value wins if a property is present in both.

Both tags and Fullstory user properties can be used for Guides and Surveys segmentation and targeting. Tags you place in window.usetifulTags, and in-session Fullstory user properties, are available for targeting immediately; they do not wait on the ~5-minute sync interval. When an in-session property change causes a user to newly match a targeting condition, Guides and Surveys re-evaluates targeting and can show matching content immediately, without an additional page load.

When Guides and Surveys resolves tag placeholders (such as {firstName}) in content, it resolves values from tags and from both user-property sources described above. Note that for security reasons, properties delivered through the ~5-minute backend sync are exposed to the client only if they're actively used in a targeting rule—that restriction does not apply to properties delivered through the in-session path, which are exposed as soon as they're set. 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 observes user properties, through two paths. Properties set with FS('setProperties', ...) or FS('setIdentity', ...) in the current session are observed live and stored in localStorage (gs_fsUser)—available immediately for placeholder replacement and targeting, and not limited to properties used in targeting rules. If a live property change causes the user to newly match a targeting condition, Guides and Surveys re-targets mid-session and can show content without a page reload. Server-only properties (set outside the browser, or before identity is established) instead sync roughly every five minutes into localStorage (gs_userProperties), and only properties referenced in a targeting rule are included in that sync. Reserved properties displayName and email are delivered only through the in-session path—they're never included in the ~5-minute sync.

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. Calling FS('setProperties', ...) in the current session also makes those properties immediately available to Guides and Surveys for targeting and placeholder substitution—see Fullstory User Properties.
  • 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 with no sync required. Fullstory user properties set in the current session are also immediate (see Fullstory User Properties); only properties that rely on the ~5-minute backend sync introduce a delay.
  • Trigger content programmatically (for example window.USETIFUL.tour.start(5)).
  • Personalize Guides and Surveys content with dynamic values using tag placeholders such as {firstName}. Placeholders resolve from both tags and Fullstory user properties.
  • 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.