Docs
  1. INSTALLATION
  2. Install Userback Code

NPM

The official npm package for embedding the Userback widget into your Javascript or Typescript application.

📘

Before you start

You'll need your Userback access token. Click the Code icon in the top-right corner of your workspace to find it.

Installation

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

npm install @userback/widget

Quickstart

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

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('YOUR_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('YOUR_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().openForm('bug');
});

Using async/await

const userback = await Userback('YOUR_ACCESS_TOKEN', options);
userback.openForm(); // Example: manually open the widget

Using .then()

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

Use cases

Build your own feedback button

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

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

Identify User

Set User info before initialization:

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

Userback('YOUR_ACCESS_TOKEN');

Identify the User at runtime

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

const userback = await Userback('YOUR_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('YOUR_ACCESS_TOKEN');

userback.showLauncher();  // Show the widget button
userback.hideLauncher();  // Hide the widget button

Widget popup

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

Widget destroy

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

Surveys

Open a specific survey

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

Close the active survey

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

For advanced customization, 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.

UserbackOptions

Define options when initializing 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' }
};

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.openForm('bug');

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);
  }
};

UserbackFormSettings

Define form behavior and field configuration inside the widget.

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

UserbackWidgetSettings

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

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

Other useful types

TypeDescription
UserbackFeedbackTypeFeedback type string — general, bug, or feature_request
UserbackDestinationTypeDestination string — screenshot, video, or form
UserbackFunctionsList of runtime methods like open, close, destroy, startSessionReplay, etc.

All available directly from:

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

Need help? Visit the Help Center or use the chat bubble on this page to contact our support team.

Updated 11 days ago

Did this page help you?