📘
JavaScript API is available on our Company Plan and above. Compare Plans | Upgrade Now

Userback lets you take control with just a little bit of JavaScript code.

You can start customizing, listening, and triggering in a matter of minutes. Have ideas for something fancy or custom that we haven't thought of yet?

💬 Contact us or 💡 Submit your idea, we'd love to hear about it.

Housekeeping

Once the widget code has been added to your web page or web application, and you would like to specifically trigger the widget via the API, you will need to enable JavaScript API via the Targeting menu of the widget settings. Select the Do not show the widget option and click Save changes.

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";

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,      
            comment_field           : true,       
            comment_field_mandatory : true,       
            display_category        : false,      
            display_feedback        : true,       
            display_attachment      : false,      
            display_assignee        : false,      
            display_priority        : false
        },
        // 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.

📘

Housekeeping

API Options

email

Type: string

name

Type: string

categories

Type: string

priority

Type: string

custom_data

Type: object

on_load

Type: function

on_open

Type: function

on_close

Type: function

after_send

Type: function

before_send

Type: function

is_live

Type: boolean

native_screenshot

Type: function

widget_settings

Type: object

API Methods

init()

type: function

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

show()

type: function

hide()

type: function

open()

type: function

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

close()

type: function

destroy()

type: function

setData()

type: function

Type: `string`

Type: `string`

Type: `string`

Type: `string`

Type: `object`

Type: `function`

Type: `function`

Type: `function`

Type: `function`

Type: `function`

Type: `boolean`

Type: `function`

Type: `object`

type: `function`

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

type: `function`

type: `function`

type: `function`

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

type: `function`

type: `function`

type: `function`