Skip to main content

Troubleshooting: Web SDK

Script not loading​

Symptoms: told function is undefined, no surveys appear.

CheckSolution
Script in <head>?Open DevTools > Elements > verify the script tag exists
Correct URL?Must be https://scripts.told.club/sdk/sdk.js
JavaScript errors?Check the browser console for errors
CSP blocking?Look for "Content Security Policy" errors in the console > see CSP section below
Ad blocker?Temporarily disable ad blocker and retry
Network blocked?Check DevTools > Network tab for failed requests to scripts.told.club

Content Security Policy (CSP)​

If your website uses a Content Security Policy, you need to allow all Told domains. CSP violations appear as errors in the browser console, typically starting with "Refused to...".

Add these domains to your CSP header or meta tag:

DomainUsed forCSP directives
https://scripts.told.clubSDK scriptscript-src
https://widget.told.clubSurvey widget (iframe)frame-src, connect-src
https://producttour.told.clubProduct tour (iframe)frame-src, connect-src
https://producttoureditor.told.clubProduct tour editor (iframe)frame-src, connect-src
https://api.told.clubAPI (GraphQL)connect-src
wss://api.told.clubWebSocket (real-time)connect-src
https://app.told.clubDashboard communicationframe-src

Example CSP header:

Content-Security-Policy:
  script-src 'self' https://scripts.told.club;
  frame-src 'self' https://widget.told.club https://producttour.told.club https://producttoureditor.told.club https://app.told.club;
  connect-src 'self' https://api.told.club wss://api.told.club https://widget.told.club https://producttour.told.club https://producttoureditor.told.club;
warning

If you only whitelist some of these domains, parts of Told may work while others silently fail. For example, surveys might load but product tours won't, or the SDK might load but can't reach the API.

SDK loaded but surveys don't appear​

  1. Run told('debug') in the browser console to see diagnostic info
  2. Check that the Source ID is correct
  3. Verify the survey is activated (Publish tab)
  4. Verify trigger conditions are met (correct URL, event, scroll depth)
  5. Check "Display only once" — may have already triggered for this visitor
  6. Clear localStorage and reload the page (this resets the anonymous user)

Invalid hostname / "Source not allowed"​

The SDK validates your domain against the URLs registered in your source settings. If you see "TOLD: Source not allowed" in the console:

  1. Check that the URL configured in Source settings matches your website's domain exactly (including protocol)
  2. For local development, make sure your source is configured for localhost
  3. If your site redirects users (e.g., from a login page to the app), set a redirection URL in Settings > Installation (step 2, "..." menu > "Edit redirection URL")

Iframe blocked​

The Told widget and product tours display inside iframes. If they're blocked:

  1. Check your CSP frame-src directive > see CSP section above
  2. Check if X-Frame-Options headers on your site are blocking cross-origin iframes
  3. If you use a reverse proxy (Nginx, Cloudflare), verify it doesn't strip or override frame-related headers

Surveys don't appear on some pages (SPA)​

The SDK automatically detects route changes in single-page applications by intercepting history.pushState(), history.replaceState(), and listening for popstate and hashchange events.

If surveys don't trigger on route changes:

  1. Verify your app uses the standard History API for navigation
  2. Check that your URL trigger pattern matches the full path (not just the hash)
  3. Test with told('debug') on the page where the survey should appear

localStorage blocked (private browsing)​

In private/incognito browsing or when cookies are blocked, localStorage may be unavailable. When this happens:

  • The anonymous ID is regenerated on each page load (the user is treated as a new visitor every time)
  • Language preferences don't persist
  • "Display only once" rules may not work as expected

If you know your users will be in a restricted storage environment, use the noLocalStorage option:

told('init', 'YOUR_SOURCE_ID', { noLocalStorage: true });

Script loaded twice​

If the SDK script is included twice on the same page (e.g., via both a direct <script> tag and a tag manager), the SDK detects duplicate initialization with the same Source ID and ignores the second call. This is handled automatically — no action needed.

However, if the script is bundled twice (e.g., by a build tool like webpack), two SDK instances may be created. To fix this:

  1. Ensure the script tag points to the hosted URL (https://scripts.told.club/sdk/sdk.js) rather than being bundled
  2. If you must bundle it, ensure your bundler doesn't create duplicate chunks

Performance impact​

The Told SDK:

  • Loads asynchronously — it doesn't block page rendering
  • Runs surveys and product tours in isolated iframes
  • Only connects to the API when triggers match or when you call SDK functions

Still stuck?​

  1. Use told('debug') to get diagnostic information
  2. Contact support at [email protected]