Go to Help Centre

Overview

Advanced customization of the Feedback Widget

What is the JavaScript Widget API?

The Userback JavaScript Widget API is a powerful tool that enables advanced users and teams to create a customized feedback collection experience. With a snippet of JavaScript, you can easily expand Userback's Feedback Widget capabilities to meet your unique needs.

Leverage the API to create custom workflows, trigger custom events, and perform advanced data manipulation. This approach provides a more flexible and tailored feedback collection experience, allowing you to gather and analyze user feedback more effectively, and ultimately enhance your products and services. With the Userback JavaScript Widget API, the possibilities for feedback collection and analysis are virtually limitless.

Access to the Userback JavaScript Widget API is included in our Company Plan and higher tiers. To see the full range of features and compare plans, check out our pricing page. Ready to upgrade your plan? Visit your Userback account to get started.

Common use-cases

🔐 User Identification - Streamline the feedback collection process on your website or app by automatically identifying users and adding their relevant details to feedback.

👆 Bind Feedback Widget to a Button or Link - Improve user experience by allowing users to easily provide feedback with a button or link that triggers the Userback feedback widget.

✍️ Prefill Name and Email Fields - Save users time by prefilling specific fields in the Userback feedback forms like name and email.

🌐 Dynamic Language Switching - Enhance the user experience for people from all over the world by switching the language of the feedback widget on the fly.

📕 Attach Custom Data to Feedback - Gain more insights into user feedback by attaching custom data, like product version, user agent or app related data.

Getting started

Here's how you can get started with the Userback JavaScript Widget API:

1. Install the Userback widget

To get started, you'll need to install the Userback widget on your website or app. You can do this by adding a JavaScript snippet to your code or by using NPM packages or SDKs for React and Vue. Check out our QuickStart Guide for Developers for step-by-step instructions.

2. Verify the installation

Before using the JavaScript Widget API, make sure that the Userback widget is correctly installed and visible on your website or app. You can verify this by checking if the widget button appears on your webpage.

3. Enable the JavaScript API

Once you've installed the widget, go to Widget Settings and select "Do not show the widget" to enable the JavaScript API and hide the Userback Feedback button. This will allow you to use the JavaScript Widget API to create custom workflows, trigger events, and perform advanced data manipulation.

If you need any help during the process, don't hesitate to reach out to our support team. We're always ready to assist you in making the most out of the Userback

API Options

email

Type: string

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

Userback.email = "[email protected]";

name

Type: string

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

Userback.name = "Someone";

categories

Type: string

Set categories in a comma-separated string

Userback.categories = "Frontend,Backend,Database,User Interface";

priority

Type: string

Set categories in a comma-separated string

Userback.priority = "Urgent"; // Urgent, High, Neutral, Low

custom_data

Type: object

Add custom data to feedback. The data will be displayed on the feedback page.

Note: Use custom_data when the Javascript API hasn't been added. Otherwise, use setData().

// Set custom data
Userback.custom_data = {
    account_id: 7,
    name: "John"
};

on_load

Type: function

The on_load event is triggered when the widget code is loaded. It is useful when you need to call API methods straight after adding the widget code that is asynchronously loaded.

<script>
    window.Userback = window.Userback || {};
    Userback.access_token = '[your widget token]';
    Userback.on_load = () => {
        Userback.open();
    };

    (function(d) {
        var s = d.createElement('script');s.async = true;
        s.src = 'https://static.userback.io/widget/v1.js';
        (d.head || d.body).appendChild(s);
    })(document);
</script>

on_open

Type: function

The on_open event is triggered when the Feedback button is clicked.

Userback.on_open = () => {
     alert("open");
};

on_close

Type: function

The on_close event is triggered when the Close button is clicked

Userback.on_close = () => {
     alert("close");
};

after_send

Type: function

The before_send event is triggered when the Send button is clicked

Userback.before_send = () => {
     alert("before send");
};

before_send

Type: function

The after_send event is triggered after feedback has been submitted to Userback

Userback.after_send = (data) => {
    console.log(data);
    // example:
    load_type: 'web',
    domain: 'www.example.com',
    page: 'https://www.example.com',
    email: '[email protected]',
    description: 'this is great!',
    update_reporter: true,
    comments: [...],
    attachment_file_name: '',
    user_agent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36',
    window_x: 364,
    window_y: 765,
    resolution_x: 1920,
    resolution_y: 1080,
    categories: '',
    custom_data: {},
    rating: 'start_5'
};

is_live

Type: boolean

Use this option to override the auto-detection of the Live vs Local website.

is_live: true:
Use this option when your website is hosted in a local environment but all of your website assets (images, CSS files, JavaScript files...etc) are all hosted publicly.

is_live: false:
Use this option to force the client side (local) screenshot engine to be used. Note: The client side screenshot engine may not generate pixel perfect screenshots. For better screenshot quality, using the live screenshot server is still recommended. Find out more about how to white list our IPs to let our screenshot servers access your website. 

Userback.is_live = true;
 
// or

Userback.init('Userback Widget Token', {
    is_live: true
});

native_screenshot

Type: function

Use browser built-in Screen Capture API to capture screenshots. This option is to be used when your web page contains complex elements (e.g. shadow DOM, iframe) that aren't compatible with our screenshot engine and you need a pixel-perfect screenshot. 

Userback.native_screenshot = true;
 
// or

Userback.init('Userback Widget Token', {
    native_screenshot: true
});

widget_settings

Type: object

Set widget options dynamically

Userback.widget_settings = {
    language                      : "en",        // string: "en", "fr", "zh-CN"...etc
    style                         : "text",      // string: "text", "circle"
    position                      : "e",         // string: "e", "w", "se", "sw"
    trigger_type                  : "page_load", // string: page_load, api, url_match
    main_button_text              : "Feedback", 
    main_button_background_colour : "#3E3F3A",  
    main_button_text_colour       : "#FFFFFF"
    device_type                   : "desktop,tablet,phone", // string
    help_link                     : "https://www.example.com", // string
    help_title                    : "Contact Us",              // string
    help_message                  : "Get in touch with us",    // string
    logo                          : '//example.com/logo.jpg',   // string
    form_settings: {
        // General Feedback Form
        general: {
            rating_type               : "star", // "star", "emoji", "heart", "thumb"
            rating_help_message       : "How would you like to rate your experience?", 
            name_field                : false,      
            name_field_mandatory      : false,      
            email_field               : true,       
            email_field_mandatory     : true,       
            title_field               : false,      
            title_field_mandatory     : false,   
            title_field_placeholder   : 'Add a title',
            comment_field             : true,       
            comment_field_mandatory   : true,
            comment_field_placeholder : 'Describe the bug in detail',
            display_category          : false,      
            display_feedback          : true,       
            display_attachment        : false,      
            display_assignee          : false,      
            display_priority          : false,
            outro_headline            : 'Thank you!',
            outro_paragraph           : 'We really appreciate your feedback.'
        },
        // Bug Form
        bug: {...},
        // Feature Request Form
        feature_request: {...}
    }
};

For Language Codes, please see our 🌐 Translations page.

API Methods

init()

type: function
syntax: Userback.init('[Userback Widget Token]', '[Options]');

The init method initializes the widget and adds the widget button to the page. When the init method is called again with a different token, a new widget button will be created and added to the page.

Options: email, name, categories, and priority

Userback.init('[Userback Widget Token]', {
    email: '[email protected]',
    name: 'Someone Someone'
});

show()

type: function

The show method displays the Userback Widget.

Userback.show();

hide()

type: function

The hide method closes the Userback Widget interface and hides it.

Userback.hide();

open()

type: function
syntax: Userback.open('[Feedback_Type]', '[Destination]');

The open method opens the Userback Widget interface in a modal dialog. The open method is to be used when the widget is set to be hidden by default.

This method would be used to open the Userback widget from a custom button or link within your UI or product.

Feedback Types: general, bug, feature_request
Destinations: screenshot, video, and form

// open the widget
Userback.open(); 

// open the "General Feedback" option
Userback.open('general');

// open the "Report a Bug" option
Userback.open('bug');

// open the "Feature Request" option
Userback.open('feature_request'); 

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

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

// open the "Feature Request" form directly
Userback.open('feature_request', 'form');

close()

type: function

The close method closes the Userback Widget interface in exactly the same way as when the widget close button is clicked.

Userback.close();

destroy()

type: function

The destroy method removes the Userback widget from the page and removes the SDK that is loaded on the page. 

Userback.destroy();

setData()

type: function

Note: Use custom_data() when the JavaScript SDK hasn't been added. Otherwise, use setData() (see below).

Userback.setData({
  account_id: 7,
  name: "John"
};

Reset custom data after JavaScript SDK is loaded.

Note:

  • The setData() method can be called multiple times. The previous data gets overwritten when setData() is called again.
  • Key names can’t contain periods ('.'), dollar signs ('$'), characters like ~`[email protected]#%^&*'{}|'". — If an unsupported character is used, the key will be created with an underscore in its place.
  • Data values must be sent as JSON strings, numbers, or booleans (true or false). We can’t accept objects, nested hashes, and array data formats. In order to bind custom data in rich format (e.g. object), use console log instead.