JotReviewJotReview
Sign Inarrow_forward

API Reference

Complete method reference for the JotReview JavaScript SDK.

Overview

The JotReview SDK exposes all methods through the global window.uj object. Every method call is queued until the SDK script finishes loading, so you can call methods immediately after the snippet without waiting for a load event.

All methods are safe to call before the SDK has fully initialized — they will be replayed in order once the script is ready.

init(projectId, options?)

Initializes the SDK with your project credentials. This must be the first method you call.

Parameters

ParameterTypeRequiredDescription
projectIdstringYesYour project ID from the JotReview dashboard
options.widgetbooleanNoShow the floating feedback button. Default: true
options.position`'left' \'right'`NoWidget button position. Default: 'right'
options.theme`'light' \'dark' \'auto'`NoColor theme. 'auto' follows system preference. Default: 'auto'
options.languagestringNoForce a locale (e.g. 'es', 'fr'). Defaults to browser language
options.trigger`'default' \'custom'`No'custom' hides the built-in button so you can use your own trigger. Default: 'default'
options.onReady() => voidNoCallback fired when the SDK has fully loaded
options.onError(err: Error) => voidNoCallback fired if initialization fails

Returns void

1window.uj.init('proj_a1b2c3d4', {
2 widget: true,
3 position: 'right',
4 theme: 'auto',
5 language: 'en',
6 onReady: () => console.log('JotReview ready'),
7 onError: (err) => console.error('JotReview init failed', err),
8});

identify(userData | null)

Associates the current user with their JotReview identity. Call this as soon as you know who the user is — typically right after login or on app load if the user has an active session.

Parameters

FieldTypeRequiredDescription
idstringYesYour internal user ID. Must be stable and unique
emailstringNoUser's email address
firstNamestringNoUser's first name
lastNamestringNoUser's last name
avatarstringNoPublicly accessible URL to the user's profile image
signaturestringNoHMAC-SHA256 signature for secure identity verification

Pass null to log out the current user and return to anonymous mode.

Returns void

1// Identify a logged-in user
2window.uj.identify({
3 id: 'usr_7x9k2m',
4 email: 'ada@example.com',
5 firstName: 'Ada',
6 lastName: 'Lovelace',
7 avatar: 'https://example.com/avatars/ada.jpg',

// Log out window.uj.identify(null); `

showWidget({ section? })

Programmatically opens the widget panel. Useful for custom trigger buttons or guided flows.

Parameters

ParameterTypeRequiredDescription
options.section`'feedback' \'roadmap' \'updates'`NoOpen directly to a specific tab. Defaults to the last active section

Returns void

1// Open widget to the default section

// Open directly to the Roadmap tab window.uj.showWidget({ section: 'roadmap' });

// Open directly to the Updates (changelog) tab window.uj.showWidget({ section: 'updates' }); `

hideWidget()

Closes the widget panel if it is currently open.

Returns void

1window.uj.hideWidget();

getWidgetState()

Returns the current state of the widget panel. Because SDK calls are asynchronous, this method returns a Promise.

Returns `Promise<{ isOpen: boolean; section: 'feedback''roadmap''updates'null }>`
1
console.log(state.isOpen); // truefalse
`

setWidgetPosition('left' | 'right')

Changes the position of the floating widget button at runtime. Useful when the button overlaps important UI at certain scroll positions.

Returns void

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

setTheme('light' | 'dark' | 'auto')

Updates the widget's color theme at runtime. Use this to synchronize the widget with a theme toggle in your application.

Returns void

1const userPrefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

// Or always follow the system preference window.uj.setTheme('auto'); `

setWidgetEnabled(boolean)

Shows or hides the widget button and disables all widget interactions. Use this to conditionally expose the widget only to certain users (e.g., beta testers or paying customers).

Returns void

1// Show the widget only for premium users
2window.uj.setWidgetEnabled(currentUser.plan === 'premium');

embed(options?)

Renders the full JotReview board as an inline embed inside a container element instead of as a floating widget. Returns an EmbedController for programmatic control.

EmbedOptions

OptionTypeRequiredDescription
container`HTMLElement \string`YesTarget element or CSS selector
pathstringNoInitial path to load (e.g. '/roadmap'). Defaults to '/'
theme`'light' \'dark' \'auto'`NoColor theme. Default: 'auto'
navbarbooleanNoShow the board's top navigation bar. Default: true
basePathstringNoPath prefix in your app's router (e.g. '/feedback'). Used for URL syncing
onReady(controller: EmbedController) => voidNoCallback fired when the embed is ready
onError(err: Error) => voidNoCallback fired if the embed fails to load

EmbedController

MethodDescription
navigate(path)Navigate to a path within the embed
destroy()Remove the embed and clean up

Returns EmbedController

1const embed = window.uj.embed({
2 container: '#feedback-container',
3 path: '/roadmap',
4 theme: 'light',
5 navbar: false,
6 basePath: '/feedback',
7 onReady: (ctrl) => console.log('Embed ready', ctrl),

// Navigate programmatically embed.navigate('/updates');

// Clean up embed.destroy(); `

open() / close() — deprecated

These are aliases for showWidget() and hideWidget() from an earlier version of the SDK. They continue to work but will be removed in a future major version.

Migration

1// Before
2window.uj.open();

// After window.uj.showWidget(); window.uj.hideWidget(); `

destroy()

Completely removes the JotReview widget from the page, cleans up all event listeners, and unloads the SDK script. After calling destroy(), you must call init() again to reinitialize.

This is useful in single-page applications when navigating to a page where the widget should not appear.

Returns void

1window.uj.destroy();