The UserTold.ai widget embeds directly in your product. Participants never leave your site — they see a floating button, answer the screener, and start an interview, all in-context.

Basic Embed

Add the script tag to your page:

<script
  src="https://app.usertold.ai/v1/widget.js"
  data-project-key="ut_pub_YOUR_KEY"
  data-screener-id="your-screener-handle"
></script>

That's it. A floating button appears in the bottom-right corner.

Configuration

Via Script Tag

<script
  src="https://app.usertold.ai/v1/widget.js"
  data-project-key="ut_pub_YOUR_KEY"
  data-screener-id="your-screener-handle"
  data-brand-color="#3b82f6"
  data-position="bottom-left"
></script>

Via JavaScript

<script src="https://app.usertold.ai/v1/widget.js"></script>
<script>
  UserTold.init({
    projectKey: 'ut_pub_YOUR_KEY',
    screenerId: 'your-screener-handle',
    brandColor: '#3b82f6',
    position: 'bottom-left',
    launcherText: 'Share your thoughts',
  });
</script>

Via Global Settings

<script>
  window.UserToldSettings = {
    projectKey: 'ut_pub_YOUR_KEY',
    screenerId: 'your-screener-handle',
    brandColor: '#3b82f6',
  };
</script>
<script src="https://app.usertold.ai/v1/widget.js"></script>

Configuration priority (highest to lowest): init() arguments > window.UserToldSettings > script tag data-* attributes > defaults.

Options

Option	Type	Default	Description
`projectKey`	string	—	Required. Public project key (`ut_pub_...`)
`screenerId`	string	—	Screener reference (ID or handle) for qualification flow
`studyId`	string	—	Study reference (ID or handle) for direct interview (skips screener)
`brandColor`	string	`#6366f1`	Hex color for buttons and accents
`position`	string	`bottom-right`	Widget position: `bottom-right` or `bottom-left`
`launcherText`	string	`Share feedback`	Text on the floating button

Either screenerId or studyId is required. Use screenerId when you want to qualify participants first. Use studyId to go straight to the interview.

Participant Flow

Launcher — Floating button with your brand color and text. Non-intrusive.
Screener — Multi-step qualification form. One question per screen with progress dots. Includes consent checkbox on the last step.
Permissions — Requests microphone and screen sharing access (both required).
Interview — AI-powered conversation. The AI adapts between talk, speak, and observe modes based on your study script.
Complete — Thank-you message with optional incentive information.

If a participant doesn't qualify, they see a polite disqualification message and can close the widget.

Programmatic Control

Start an Interview Directly

UserTold.startInterview({
  screenerId: 'your-screener-handle'
});

Deep Links via URL Parameters

Direct participants to a specific screener or study by adding URL parameters:

https://your-site.com?ut_start=beta-users
https://your-site.com?ut_study=checkout-q1

The widget auto-opens on page load when these parameters are present.

Identify Participants

UserTold.identify('user_123', {
  email: 'user@example.com',
  name: 'Jane Doe',
  plan: 'pro',
  // Any custom traits
});

Styling

The widget renders inside a Shadow DOM to avoid CSS conflicts with your site. It uses fixed positioning with a high z-index to float above your content.

Customizable via configuration:

Brand color — applied to buttons, progress indicators, and accents
Position — bottom-right or bottom-left corner
Launcher text — button label

Technical Details

The widget loads in two parts:

Loader (widget.js, ~3-4KB gzip) — reads configuration, renders the launcher button
UI chunk (lazy-loaded) — full interview UI, loaded only when the participant clicks the launcher

This keeps the initial page impact minimal.

Troubleshooting

Issue	Solution
Widget doesn't appear	Check that `projectKey` is set and valid (`ut_pub_...`). Ensure `screenerId` or `studyId` is configured.
Microphone permission denied	The participant must grant microphone access. Check browser permission settings.
"No active study linked"	The screener must have a linked study with status `active`.
Widget styles look broken	Check for Content Security Policy (CSP) rules that might block inline styles or the widget script.
Interview hangs	Check browser console for WebSocket errors. Verify the study is active and API keys are configured.

Widget Integration