Overview

The Userback JavaScript package allows you to seamlessly integrate the Userback Widget into your JavaScript or TypeScript application for feedback collection and management.

Official NPM Package: @userback/widget
Official GitHub Repository: Userback JavaScript SDK

Prerequisites

Before you begin, ensure the following:

Userback Workspace: A workspace is needed to collect and manage feedback.
Access Token: Retrieve your token via the Code Icon in your workspace.
Plan Requirements: Available on all plans.

Installation

To install the Userback package and embed the widget in your application, use the following command:

NPM Installation

npm i @userback/widget

Quickstart

Embed the Userback Widget in your application using the example below:

Code Example

import Userback from '@userback/widget';

// Optionally identify logged-in users
const options = {
  user_data: {
    id: "123456", // Unique user ID
    info: {
      name: "someone", // User's name
      email: "[email protected]" // User's email
    }
  }
};

Userback('**Userback Access Token**', options);

import Userback, { UserbackOptions } from '@userback/widget';

// Optionally identify logged-in users
const options: UserbackOptions = {
  user_data: {
    id: "123456", // Unique user ID
    info: {
      name: "someone", // User's name
      email: "[email protected]" // User's email
    }
  }
};

// Initialize Userback with the access token and options
Userback('**Userback Access Token**', options);

Accessing the Userback Instance

If you need to programmatically interact with Userback (e.g., open the widget, trigger feedback, etc.), you can retrieve the instance like this:

Using `getUserback`

import { getUserback } from '@userback/widget';

document.querySelector('button.bug-report').addEventListener('click', (event) => {  
    getUserback().open('bug');
});

Using `async/await`

const userback = await Userback('**Userback Access Token**', options);
userback.open(); // Example: manually open the widget

Using `.then()`

Userback('**Userback Access Token**', options).then((userback) => {
  userback.open(); // Example: manually open the widget
});

Use cases

Build your own feedback button

Use a custom button to control when the widget is displayed.

Userback('**Userback Access Token**', { autohide: true }).then(ub => {
    document.querySelector('.my-own-help-button').addEventListener('click', function() {
        ub.show();
    });
});

Identify User

Set User info before initialisation:

Userback.user_data = {
  id: 'USR789',
  info: {
    name: 'Jane Doe',
    email: '[email protected]',
    plan: 'Enterprise',
    account_id: '789XYZ'
  }
};

Userback('**Userback Access Token**');

Identify the User at runtime

If your app fetches user info dynamically (e.g. after login), call identify() after initialising the widget:

const userback = await Userback('**Userback Access Token**');

userback.identify('USR789', {
  name: 'Jane Doe',
  email: '[email protected]',
  plan: 'Enterprise',
  account_id: '789XYZ'
});

Note:

identify() can be called multiple times, and it overwrites previous data.
Key names should not contain special characters.
Values must be JSON strings, numbers, or booleans.

Widget button

const userback = await Userback('**Userback Access Token**');

userback.show();  // Show the widget button
userback.hide();  // Hide the widget button

Widget popup

userback.open('bug'); // Opens screenshot tool with "bug" feedback form

Widget destroy

userback.destroy(); // Completely remove userback code form your website

Surveys

Open a specific survey

userback.openSurvey('%%survey_id%%'); // Opens a specific survey

Close the active survey

userback.closeSurvey(); // Closes the currently open survey

For advanced customisation, refer to the JavaScript SDK Documentation.

Typescript

The Userback SDK provides full TypeScript support out of the box.
You can import all necessary types directly from the @userback/widget package.

Available

1. `UserbackOptions`

Define options when initialising the Userback widget.

import type { UserbackOptions } from '@userback/widget';

Example:

const options: UserbackOptions = {
  email: "[email protected]",
  user_data: { id: 123, info: { name: "John Doe" } },
  widget_settings: { style: 'circle' }
};

2. `UserbackWidget`

Represents the Userback instance returned after initializing.

import type { UserbackWidget } from '@userback/widget';

Example:

const userback: UserbackWidget = await Userback('your-access-token', options);
userback.open('bug');

3. `UserbackAfterSendData`

Defines the feedback data sent after submitting a report.

import type { UserbackAfterSendData } from '@userback/widget';

Usage inside after_sendcallback:

const options: UserbackOptions = {
  after_send: (data: UserbackAfterSendData) => {
    console.log('Feedback submitted:', data);
  }
};

4. `UserbackFormSettings`

Define form behavior and field configuration inside the widget.

import type { UserbackFormSettings } from '@userback/widget';

5. `UserbackWidgetSettings`

Configure the widget’s appearance, language, position, and embedded forms.

import type { UserbackWidgetSettings } from '@userback/widget';

6. `Other Useful Types`

Type	Description
`UserbackFeedbackType`	`general`
`UserbackDestinationType`	`screenshot`
`UserbackFunctions`	List of runtime methods like `open`, `close`, `destroy`, `startSessionReplay`, etc.

All available directly from:

import type { UserbackFunctions, UserbackFeedbackType, UserbackDestinationType } from '@userback/widget';

🛟 Support

Need help? Here’s how to get assistance:

Log in to your Userback workspace.
Click the Help Center icon in the top-right corner.
Select Contact us to start a chat with our support team.