Widget SDK reference

This page documents the browser SDK exposed as window.uj.

If you are looking for the public REST API instead of the widget SDK, use /docs/api.

`init(projectId, options?)`

Initializes UserJot for the current page.

window.uj.init('YOUR_PROJECT_ID', {
  widget: true,
  position: 'right',
  theme: 'auto',
  trigger: 'default',
  locale: 'auto',
  onReady: () => {},
  onError: (error) => {}
});

Parameters

projectId: your UserJot project ID
options.widget: set to true to enable the floating widget launcher
options.position: 'left' or 'right'
options.theme: 'auto', 'light', or 'dark'
options.trigger: 'default' or 'custom'
options.locale: 'auto' or a locale string such as 'en-US'
options.onReady: called after initialization succeeds
options.onError: called if initialization fails

`identify(options | null)`

Identifies the current user.

window.uj.identify({
  id: 'user_123',
  email: 'john@example.com',
  firstName: 'John',
  lastName: 'Doe',
  avatar: 'https://example.com/avatar.jpg',
  signature: 'SERVER_GENERATED_SIGNATURE',
  traits: {
    plan: 'pro',
    trialing: false
  },
  companies: [
    {
      id: 'company_456',
      name: 'Acme Inc.',
      domain: 'acme.com',
      logo: 'https://example.com/acme-logo.png',
      traits: {
        plan: 'enterprise',
        industry: 'Software',
        companySize: 250
      }
    }
  ]
});

Parameters

id: required stable user ID from your system
email: optional email address
firstName: optional first name
lastName: optional last name
avatar: optional avatar URL
signature: optional server-generated HMAC signature
traits: optional user traits object
companies: optional array of company objects

Pass null to clear the current identity:

window.uj.identify(null);

`setTrait(key, value)`

Updates one user trait after identification.

window.uj.setTrait('plan', 'enterprise');
window.uj.setTrait('trialing', false);
window.uj.setTrait('teamSize', 42);
window.uj.setTrait('plan', null);

Parameters

key: trait name
value: string, number, boolean, or null

Passing null removes that trait key. The user must already be identified.

`showWidget(options?)`

Opens the widget.

window.uj.showWidget();
window.uj.showWidget({ section: 'feedback' });
window.uj.showWidget({ section: 'roadmap' });
window.uj.showWidget({ section: 'updates' });

Parameters

options.section: 'feedback', 'roadmap', or 'updates'

`hideWidget()`

Closes the widget.

window.uj.hideWidget();

`getWidgetState()`

Returns the current widget state.

const state = window.uj.getWidgetState();
// { isOpen: boolean, section: 'feedback' | 'roadmap' | 'updates' | null }

`setWidgetPosition(position)`

Moves the launcher to the left or right side of the screen.

window.uj.setWidgetPosition('left');
window.uj.setWidgetPosition('right');

`setWidgetEnabled(enabled)`

Temporarily disables or re-enables the widget launcher.

window.uj.setWidgetEnabled(false);
window.uj.setWidgetEnabled(true);

`setTheme(theme)`

Changes the widget theme after initialization.

window.uj.setTheme('dark');
window.uj.setTheme('light');
window.uj.setTheme('auto');

`askForFeedback(options?)`

Shows a toast prompt that sends the user into the feedback flow when they click the action.

window.uj.askForFeedback();
window.uj.askForFeedback({
  title: 'Have feedback?',
  description: 'Tell us what would make this workflow better.',
  duration: 15000
});

Parameters

options.title: optional toast title
options.description: optional toast description
options.duration: optional duration in milliseconds

`redirect(options?)`

Redirects the user to your public UserJot site.

window.uj.redirect();
window.uj.redirect({ to: 'roadmap' });
window.uj.redirect({ to: 'feedback', openFeedback: true });
window.uj.redirect({ to: 'updates', newTab: true });

Parameters

options.to: 'feedback', 'roadmap', or 'updates'
options.openFeedback: when true, adds the openFeedback query parameter
options.newTab: when true, opens the destination in a new tab

This helper resolves the correct public domain for the current project and automatically appends the client token when automatic login is available.

`embed(options?)`

Embeds the public UserJot experience in an iframe and returns a controller.

const embed = window.uj.embed({
  container: '#feedback-embed',
  path: '/roadmap',
  theme: 'auto',
  basePath: '/feedback',
  onReady: () => {},
  onError: (error) => {}
});

Parameters

options.container: CSS selector or HTMLElement
options.path: initial path inside the public UserJot site
options.theme: 'auto', 'light', or 'dark'
options.basePath: parent-site path prefix for URL syncing
options.onReady: called when the embed is ready
options.onError: called if creation fails

Return value

embed(...) returns either an EmbedController or null.

embed.navigate('/updates');
embed.destroy();

For the full guide, use /docs/iframe-embed.

`destroyEmbed()`

Destroys the current iframe embed instance if one exists.

window.uj.destroyEmbed();

`destroy()`

Removes the widget instance and clears its runtime state.

window.uj.destroy();

This is mainly useful in environments where your page lifecycle needs to tear down and recreate the SDK cleanly.

`debug(options?)`

Enables debug logging and optionally overrides the API base URL.

window.uj.debug();

This is primarily for development and troubleshooting.