Elevate your feedback strategy with the Userback JavaScript SDK. This allows you to interact directly with the Userback Feedback Widget with a little bit of JavaScript, offering a tailored workflow and experience that aligns with your specific business objectives and product goals.

🔐 Company Plan or higher required - To explore subscription options, visit our plans and pricing.

For basic integration and support for Single Page Apps, the init() function is accessible on all subscription levels.

Getting Started

Installation

Option A: Package Managers

For JavaScript, React, and Vue.

npm i @userback/widget
# or
yarn add @userback/widget

npm i @userback/react
# or
yarn add @userback/react

npm i @userback/vue
# or
yarn add @userback/vue

Option B: Script Tag

Insert the script in the HTML head section:

<script src="https://static.userback.io/widget/v1.js"></script>

Initialization

Use your unique project-based Widget Access Token.

Userback.init('widget_access_token', {
    email: '[email protected]',
    name: '',
    on_load: () => {
      console.log('widget is loaded');
    }
});

SDK Methods

Widget Initialization

init(widget_access_token: string)

Initializes the Userback widget with an access token. Should be called first to set up the widget.

Userback.init('widget_access_token');

Widget Button

show(), hide()

Show or hide the Userback widget button on the screen.

Userback.show(); // Show the widget
Userback.hide(); // Hide the widget

Widget Pop-up

open(type: string, destination: string)

Opens the widget for specified feedback type and destination. 💡 Tip: Hide the Widget Button with Widget Settings.

Feedback Types: general, bug, and feature_request

Destinations: screenshot, video, and form

Userback.open('bug', 'screenshot'); // open the screenshot tool and then direct to the bug form

close()

Closes the Userback widget popup.

Userback.close();

Widget Destroy

destroy()

Removes the Userback widget and SDK from your application.

Userback.destroy();

SDK Options

Name and Email

Automatically populate Feedback name and email fields without relying on User Identification.

email: string

Set the default email. The email field will be auto-filled in the feedback form.

Userback.email = "[email protected]";

name: string

Set the default name. The name field will be auto-filled in the feedback form.

Userback.name = "Someone";

Categories and Priority

categories: string

Define the categories that can be chosen in the feedback form.

Userback.categories = "Frontend,Backend,Database,UI";

priority: string

Set the default priority level for feedback.

Priority Types: low, neutral, high, and urgent

Userback.priority = "urgent";

Identify Users

identify(uid: string, attributes: object)

Identifies a logged-in user with unique attributes. Should be used after initializing the widget.

MyApp.on('login', () => {
  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.

user_data: object

Use this when the JavaScript SDK hasn't been initialized. This will identify the user and provide a similar set of attributes.

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

Custom Data

setData(data: object)

Capture session-specific or dynamically changing data. Use this method after initializing the widget with init().

Userback.setData({
    AB_test_variant: 'B',
    time_on_page: '2m 15s'
});

Note:

• setData() can be called multiple times, overwriting previous data.
• Key names should not contain special characters.
• Values must be JSON strings, numbers, or booleans.

custom_data: object

• Capture static custom data when the JavaScript SDK hasn't been initialized.

Userback.custom_data = {
    page_name: 'Checkout',
    user_status: 'Active'
};

Event Handling

on_load: function, on_open: function, on_close: function, before_send: function, after_send: function

Customize the widget's behavior during specific events.

Userback.on_load = () => {
  console.log("Widget Loaded");
};

Build Environment

is_live: boolean

Configure the screenshot engine based on your website's hosting environment.

• is_live: true: Use this when your website is locally hosted, but assets like images and scripts are publicly accessible. Enables the live screenshot server for higher-quality captures.
• is_live: false: Forces the use of the client-side screenshot engine, which may not generate pixel-perfect images. Recommended for restricted or isolated environments. Learn how to whitelist our IPs for improved quality.

Userback.is_live = true;

Native Screenshot

native_screenshot: boolean

Force the browser's built-in Screen Capture API for capturing screenshots.

Userback.native_screenshot = true

Note: Useful when dealing with complex web elements like shadow DOM and iframes. This enables pixel-perfect screenshots that may not be achievable using our default screenshot engine.

Widget Settings

widget_settings: object

Dynamically configure various aspects of your widget's appearance and functionality.

Global Settings

Language (string): "en", "fr", "zh-CN" Language code options
Style (string): "text", "circle"
Position (string): "e", "w", "se", "sw"
Trigger Type (string): "page_load", "api", "url_match"
Main Button Text (string)
Main Button Background Colour (string) "#000FFF"
Main Button Text Colour (string) "#000FFF"
Device Type (string): "desktop", "tablet", "phone"
Help Link (string)
Help Title (string)
Help Message (string)
Logo (string)

Form Settings

Rating Type (string): "star", "emoji", "heart", "thumb", "numbers"
Rating Help Message (string)
Name Field (boolean)
Name Field Mandatory (boolean)
Email Field (boolean)
Email Field Mandatory (boolean)
Title Field (boolean)
Title Field Mandatory (boolean)
Comment Field (boolean)
Comment Field Mandatory (boolean)
Display Category (boolean)
Display Feedback (boolean)
Display Attachment (boolean)
Display Assignee (boolean)
Display Priority (boolean)

Userback.widget_settings = {
    language                      : "en",
    style                         : "text",    
    position                      : "e",
    trigger_type                  : "page_load", 
    main_button_text              : "Feedback", 
    main_button_background_colour : "#3E3F3A",  
    main_button_text_colour       : "#FFFFFF"
    device_type                   : "desktop,tablet,phone", 
    help_link                     : "https://www.example.com", 
    help_title                    : "Contact Us",              
    help_message                  : "Get in touch with us",    
    logo                          : '//example.com/logo.jpg',   /
    form_settings: {
        // General Feedback Form
        general: {
            rating_type             : "star",
            rating_help_message     : "How would you like to rate your experience?", 
        },
        // Bug Form
        bug: {...},
        // Feature Request Form
        feature_request: {...}
    }
};

Support

Thank you for exploring the Userback JavaScript SDK documentation. Feel free to send a message our support team, we'll gladly assist in optimizing your Userback implementation.