Guides and Surveys - Troubleshooting

If you would like to evaluate Guides and Surveys, please reach out to a member of your account team or fill out this form to be connected with a Fullstory team member.

Who can use this feature?
- Part of Guides and Surveys, an add-on for Business, Advanced, and Enterprise plans.
- Requires an Admin, Architect, or Standard role to configure.

Guides and Surveys is in active development. Product functionality and documentation may change without notice.

Guides and Surveys content—tours, checklists, banners, surveys, and smart tips—can fail to show, reach the wrong people, come back after it's dismissed, or look different than it did in preview. Find the symptom that matches what you see below. If the problem is targeting, use the browser console tool to see which condition failed.

Before launch, run through the Prelaunch Checklist. For what preview does and doesn't validate, see Testing in Preview and Production.

This article covers the following:

Rule these out first

A few known limits cause problems that can look like a configuration mistake. Check these before you dig into a specific content item.

  • Anchored content depends on the page structure, so a site update can break an anchor or trigger.
  • Mobile supports a narrower set of targeting options than desktop. See Mobile and desktop differences.
  • A long, manually pasted list of emails or IDs is a weak way to build an audience. See Long pasted lists.
  • Routing content through a custom endpoint or relay isn't currently supported in every environment.

Common issues

The sections below are grouped by what you see. Each one lists the usual causes and what to check.

Content is not showing

When content doesn't show for anyone, the cause is usually its publish state, its targeting, or something in the browser blocking it. Check the following:

  • Confirm the content is published and not still in draft.
  • Confirm page targeting is set to the page where you want the content to appear.
  • Review the targeting logic in the content settings.
  • Check whether a frequency or throttling limit is holding the content back.
  • Rule out a browser ad blocker, which can prevent content from loading at all.

If those all check out, use the browser console tool to see which targeting condition is blocking the item.

Preview does not match what you published

Preview is for checking copy, styling, and layout. It intentionally skips some of the rules that apply to real visitors. For the full comparison, see Testing in Preview and Production.

Page and URL rules skipped in preview

Preview lets you review content anywhere on your site, so it skips page and URL targeting rules. Published content follows the rules as configured. To see how a rule would evaluate without applying it, use the extension's Targeting view.

Extension preview alongside the live snippet

If you preview with the browser extension on a page where the Guides and Surveys snippet is also running, preview can behave in ways that don't reflect production. For a reliable check, publish a version limited to your own account and verify it live.

Test accounts versus first-time visitors

Your own test account isn't a first-time visitor, so it can behave differently than a new user. Test in a new or freshly logged-in session. After launch, segment the users who saw the content and watch their sessions to confirm it behaves as expected.

The wrong people see it, or too few do

When the audience is off, the miss is usually the value being matched, how fast that value updates, or how the list was built. For how each condition works, see Page and Audience Targeting.

Coworkers seeing customer-facing content

Exclude users with a user property unique to your organization, such as an email domain or account. If there are other users you always want to exclude, create a Guides and Surveys or Fullstory segment and exclude it from each item.

People outside the audience

A property that updates periodically, rather than instantly, can briefly match the wrong person while it catches up. A close partial value can also match as if it were a full one. Target the most precise value that is available immediately.

Fewer people than the audience includes

New users, new accounts, and freshly imported lists can take a short time to sync before targeting recognizes them. Also confirm the field and value you target match what's stored for your users. Targeting a similarly named but different field can produce a rule that matches no one.

Long pasted lists

Large, manually pasted lists of emails or IDs have practical limits. To target a large or specific group, import the users as a tag or segment instead. If you already have a Fullstory segment for analytics, you can target that segment directly.

Mobile and desktop differences

Mobile supports a narrower set of targeting options than desktop, so a rule that works on the web may not apply on mobile. Confirm the targeting you use is supported on both platforms.

To see which targeting condition an item matches or fails on the current page, use the browser console tool.

It comes back, or progress resets

Frequency and completion are recorded in the browser. When that record is missing, shared, or stale, content comes back. For recurrence options, see Triggering Content.

Dismissed content returning

Check whether the trigger, automatic or manual, is set to Only once.

If someone has several tabs of your site open, dismissing content in one tab doesn't update tabs that were already loaded. The content can reappear in an older tab until it is refreshed.

Content returning on a later visit, login, or device

Guides and Surveys records which content a user has already seen in the browser's localStorage. Recurrence settings—such as Every x days or Only once—depend on that record. If your application clears localStorage on page load, logout, or session expiry, Guides and Surveys has no record of the prior display and the content can appear again on the next visit. Private or incognito windows, and some ad blockers, can have the same effect.

If your application needs to clear localStorage, keep any key that starts with uf_, plus _uid and _fs_lua. Those Guides and Surveys keys must persist so frequency settings work as configured.

Progress reset after logout

If your site clears browser storage on logout or session expiry, it can wipe saved progress before the new session syncs. Completed content can then look incomplete again.

Shared progress on one account

If everyone logged in to an account is tracked under one shared identity, one person's completed or dismissed state applies to everyone on that account. A tour or checklist can then appear to reset or skip at random. Track progress per person, not per account.

It looks wrong, stacks, or fires at the wrong time

Timing and layout follow the page the content appears on. Several eligible items, including your product's own onboarding, can also compete for the same moment.

Styling or layout that does not match the design

Content picks up styles from the page, so a change to your site's styles can change how it looks. Check whether anything changed on the page where it appears.

Content that shows too early, too late, or flashes

Compare the trigger and timing settings with when the page and its elements finish loading. Also confirm the page itself isn't taking unusually long to load.

Several items at once

Check what else is targeted to the same page or moment, including onboarding or setup screens built into your product. For how Guides and Surveys orders eligible content, see Content Priority.

Two versions after a theme or tab toggle

Targeting is evaluated when the page loads, not on every change within the page. After a change such as switching between light and dark mode or changing tabs, content that should show or hide may not update until the next reload. Use one item that adapts to each state, rather than two items targeted to each state.

Content people cannot close

Not every content type adds a close or skip control by default. Check that the content includes one, and that it is visible in the design.

Slower pages

Check how much loads on the page at once. Several content items, heavy images or video, or a very long survey can add noticeable weight. Reduce media size or the number of items targeted to that page.

An anchor or trigger no longer matches the page

Content can be anchored to or triggered by an element on the page. Even a small site update can hide that element, so a step, tooltip, or trigger that used to work stops finding its target, even though nobody edited the content. Check that the targeted elements still appear on the page, and ask your developers whether anything changed recently. For more stable targets, use a Fullstory Element, which follows selector changes made in Fullstory, or see Finding Element Selectors on Your Website to choose more stable selectors.

Diagnose targeting in the browser console

Guides and Surveys includes a browser-console tool that re-evaluates every targeting condition for a specific content item and reports exactly why it does or doesn't match the current page. You don't need to be a developer to use it. It only requires opening your browser's developer console and pasting one line of code.

Prerequisites:

  • Guides and Surveys installed and loaded on the page you're testing.
  • Access to your browser's developer console.

For the complete technical reference of window.USETIFUL.troubleshoot, including every field returned in the console report, see Troubleshoot in the Guides and Surveys developer documentation.

  1. Open your browser's developer console. Confirm the troubleshoot tool is ready by pasting the following—it returns true once available:

    typeof window.USETIFUL?.troubleshoot?.checkTargeting === 'function'
  2. Find the content ID. Find the item's content type and ID from its URL in the Guides and Surveys editor. See Finding the contentId in the developer documentation for examples by content type.
  3. Run checkTargeting. Call it with the content type and ID:

    window.USETIFUL.troubleshoot.checkTargeting(contentType, contentId)

    For example:

    // Check whether a survey is targeted to show on the current page
    window.USETIFUL.troubleshoot.checkTargeting('survey', '1f15910d-ba3c-6b58-9c3c-b95f19c98615');
    
    // Check a tour by its numeric ID
    window.USETIFUL.troubleshoot.checkTargeting('tour', 1);

    checkTargeting prints a color-coded report directly to the console.

  4. Read the results. The report shows whether the item currently matches the page, plus the result of each targeting condition, so you can see exactly which condition is blocking it:

    • Overall: Whether the item currently matches the page and would show.
    • Throttling: For autoplayed tours and surveys, whether Content Throttling limits are currently blocking the item, separately from targeting. Manually triggered content, and all other content types, are never throttled.

    If checkTargeting logs an error and returns null, either the content type isn't recognized, or no content item with that ID is currently loaded on the page. Double-check the type and ID from the editor URL and try again.

Identity inconsistency error

This error means the Guides and Surveys userId doesn't match the Fullstory user ID for the current session.

The Guides and Surveys userId—set with window.usetifulTags.userId or window.USETIFUL.user.setId()—must exactly match the value passed to FS('setIdentity', ...) for that visitor. For visitors who aren't identified in Fullstory, don't send a placeholder value such as -1 or "PublicAnonymousUser"; leave the Guides and Surveys userId unset instead.

For more on how the two identities relate, see Working with Fullstory Analytics in the Guides and Surveys developer documentation.

Before you contact support

If you still need help, have the following ready so your ticket moves faster:

  • The page URL where the issue happens, and whether it requires a login
  • A screenshot or short recording of what you see
  • The name of and link to the tour, survey, banner, smart tip, or checklist involved
  • The browser and device you tested on
  • Roughly when the issue started
  • Whether it affects one person, a specific group, or everyone

If the question is about targeting, run the browser console check first. It may answer the question directly.


Was this article helpful?

Got Questions?

Get in touch with a Fullstory rep, ask the community or check out our developer documentation.