Skip to main content

Web SDK Installation

Install the Told SDK on your website to display in-app surveys and product tours.

The Installation page in your dashboard​

After creating a web source, Told brings you to its Installation page (sidebar Settings → Installation). This page is a guided wizard that walks you through the four steps required to get the SDK running.

You can come back to it at any time from the source sidebar.

1. Add the script​

This step shows your Source ID and the JavaScript snippet you need to add to the <head> tag of your website. Click Copy code to copy the snippet to your clipboard.

The snippet looks like this:

<script>
  // Told SDK loader
  // ...
  told('init', 'YOUR_SOURCE_ID');
</script>

The actual snippet on the dashboard already contains your Source ID — you don't need to paste it manually.

2. Add your domain​

Step 2 lists the domains registered for this source. Each row shows:

ColumnDescription
DomainThe URL where the SDK is allowed to load (set when you created the source)
StatusWhether Told has detected the SDK on that domain
ValidationA Verify domain button to trigger the check

Next to each domain, a contextual menu (the "..." icon) gives you two options:

  • Edit redirection URL
  • Delete

Redirection URL​

Sometimes the SDK loads on a URL different from the one you registered. A common case is authentication-protected apps: the user first lands on a public URL (e.g., a login page), then your server redirects them to the actual app URL where the SDK actually runs. Without configuration, Told would reject the SDK because it's loading from a domain that doesn't match the registered one.

To handle this, you can set a redirection URL on the domain via the "..." menu → Edit redirection URL. Enter the URL the user is redirected to after the protected entry point, and save. The SDK will then be allowed to run on both URLs.

3. Verify installation​

Once you've added the script to your website, click Verify installation. Told opens a verification page that checks if the SDK is correctly loaded on your domain.

  • If the check succeeds, the domain status changes and you can move on.
  • If the check fails, you'll see "We can't find our code on your website" with three buttons: Try again, Read doc, and Contact support. A Skip this step link lets you bypass verification if you know the SDK is correctly installed.

The same verification flow is triggered by the Verify domain button in step 2 — both buttons lead to the same check.

4. Identify your users (optional)​

Step 4 shows a snippet for the told('identify', { ... }) function. Calling it lets you associate a Told session with one of your authenticated users, so responses can be tied to a specific account.

This step is optional but recommended if you want survey responses to be linked to identified users instead of anonymous sessions.

See Identify users for the full reference.

Prerequisites​

Installation steps​

  1. Create a source in Told and copy your Source ID from the Installation page
  2. Add the SDK script to your website (see method-specific guides below)
  3. Verify the installation using the Verify installation button in your source settings
  4. Identify users when they log in (optional but recommended)
  5. Create and publish your first survey

Installation methods​

Choose the method that matches your tech stack:

Verify installation​

After adding the SDK, verify it's working:

  1. Go to your source in the Told dashboard
  2. Click Verify installation
  3. Told opens your website and checks if the SDK is loaded
  4. The status should change to Installed

Manual verification: Open your browser's developer console and run:

told('debug', 'YOUR_SOURCE_ID')

This displays diagnostic information about your source, active surveys, and any configuration issues.

Content Security Policy (CSP)​

If your website uses a Content Security Policy, you'll need to add Told's domains to your policy. See the CSP configuration guide.