JavaScript API: Advanced Feedback Collection

Take control of the feedback experience! - The JavaScript API allows developers to dynamically customize and collect feedback directly from their application. This gives them the freedom to tailor and automate the user experience by prefilling fields, attaching custom values, capturing user data, changing languages, and setting dynamic widget options.

Personalize the user feedback experience with User Identification by automatically gathering metadata such as customer type, value and account ID. This helps teams understand what their customers need and prioritize their feedback, leading to faster problem solving. It's perfect for reporting bugs, making feature requests, testing user acceptance and measuring customer satisfaction.

Advanced users can create bespoke experiences and journeys by doing things like triggering feedback requests at the perfect time or binding the feedback widget to a custom element like a button or link.

Check out some more examples of what our users are doing with the JavaScript API:

• Bind the feedback widget to a button or link [Quick Guide]

• Prefill fields such as name and email [Quick Guide]

• Identify users by id include details like plan, value, and owner [Quick Guide]

• Control widget features and appearance dynamically

• Switch languages on the fly [Quick Guide]

• Add custom data for filtering and organizing feedback [Quick Guide]

• Set actions when certain events happen like feedback submission

Getting Started with the API

Begin using the JavaScript API here. You'll need a Company or Premium plan to access it, upgrade or contact us today to learn more, we're here to help.

1. Install the Userback Widget: We suggest reviewing our Installation Guide to find the best method for your specific needs. For compatibility with more complex frameworks and apps, we recommend using "Method 2: Script tag".

2. Enable the JavaScript API: To do this, navigate to the Targeting section in Widget Settings and select the "Do not show the widget" option. Click "Save changes" to apply the changes.

3. Review the list of methods: For interacting with the Widget, for example, you can use the open() and close() methods to open and close the widget.

4. Review the list of options: Customizing the Widget, for example, you can use the email, name, categories, priority, and custom_data options to pre-fill fields or add additional information to feedback.

A list of methods for interacting with the Userback Widget

• init(): initializes the widget and adds the widget button to the page. This method should be called once to start using Userback on the website

• show(): displays the Userback widget. This method can be used to show the widget after it has been hidden using the hide() method

• hide(): closes and hides the widget. This method can be used to hide the widget temporarily without removing it from the page

• open(): opens the Userback widget in a modal dialog, accepts feedback type and destination as optional parameters. This method can be used to open the widget from a custom button or link within your UI or product

• close(): closes the widget in the same way as when the widget close button is clicked. This method can be used to close the widget programmatically

• destroy(): removes the Userback widget from the page. This method can be used to remove the widget and stop using Userback on the website

A list of options for customizing the Userback Widget

• email: sets the default email. This option can be used to pre-fill the email field in the feedback form

• name: sets the default name. This option can be used to pre-fill the name field in the feedback form

• categories: sets categories in a comma-separated string. This option can be used to filter feedback based on category

• priority: sets the default priority. This option can be used to set the default priority level for feedback

• custom_data: adds custom data to feedback. This option can be used to add additional information to feedback

• setData(): can be used to add custom data to feedback. This method can be used to add additional information to feedback after the widget has been initialized

• on_load: callback function that is called when the widget is loaded

• on_open: callback function that is called when the widget is opened

• on_close: callback function that is called when the widget is closed

• before_send: callback function that is called before feedback is sent, can be used to validate or modify feedback before submission

• after_send: callback function that is called after feedback is sent, can be used to track the submission or display a confirmation message

• is_live: if set to true, the widget will be live and feedback will be sent immediately, if set to false, the widget will be in test mode and feedback will not be sent

• native_screenshot: This option enables the use of the browser's built-in Screen Capture API to capture screenshots.

• widget_settings: This option allows you to customize the widget to suit the specific needs of your website or app. You can use it to adjust settings such as position, colors, text, and forms, ensuring that the widget matches the design of your website and provides the desired functionality.

API Methods: Definitions & Examples

init(token, options)

type: function

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.

Userback.init('1|3|IjXmeq4nrQRoPlmr84', {
email: 'someone@example.com',
name: '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(feedback_type, destination)

type: function

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_type (optional): "general", "bug", "feature_request"
destination (optional): 'screenshot', 'video' and 'form'

Userback.open(); // open the widget
Userback.open('general'); // open the "General Feedback" option
Userback.open('bug'); // open the "Report a Bug" option
Userback.open('feature_request'); // open the "Feature Request" option
Userback.open('bug', 'screenshot'); // open the screenshot tool and then direct to the bug form
Userback.open('bug', 'video'); // open the video recording tool and then direct to the bug form
Userback.open('feature_request', 'form'); // open the "Feature Request" form directly

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

API Options: Definitions & Examples

email

type: string

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

Userback.email = "example@example.com";

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 the default priority.

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 SDK hasn't been added. Otherwise, use setData() (see below).

window.Userback = window.Userback || {};

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

// Add JavaScript SDK
Userback.access_token = '[your widget token]';
(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);

setData()

type: function

// Add JavaScript SDK
window.Userback = window.Userback || {};
Userback.access_token = '[your widget token]';
(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);

// Reset custom data on button click
document.querySelector('#btn').addEventListener('click', () => {
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 ~`!@#%^&*'{}|\'". — 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 object, nested hashes and array data formats. In order to bind custom data in rich format (e.g. object), use console log instead.

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

before_send

type: function

The before_send event is triggered when the Send button is clicked

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

after_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: 'example@example.com',
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 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.

<script>
window.Userback = window.Userback || {};
Userback.access_token = '[your widget token]';
Userback.is_live = true;
(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>

or 

Userback.init('[your widget token]', {
is_live: true
});

native_screenshot

type: boolean

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.

Note: this feature requires the Company plan.

<script>
window.Userback = window.Userback || {};
Userback.access_token = '[your widget token]';
Userback.native_screenshot = true;
(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> 

or

Userback.init('[your 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: {...}
}
};

Language Code:

Examples:

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

Userback.email = "example@example.com";
Userback.widget_settings = {
language: "fr"
};
Userback.custom_data = {
a_id: 2,
name: "John"
};

(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>

🔐 Who is this article for?