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
string
Set the default email. The email field will be auto-filled in the feedback form.
Userback.email = "[email protected]";
name
Type: string
string
Set the default name. The name field will be auto-filled in the feedback form.
Userback.name = "Someone";
categories
Type: string
string
Set categories in a comma-separated string
Userback.categories = "Frontend,Backend,Database,User Interface";
priority
Type: string
string
Set categories in a comma-separated string
Userback.priority = "Urgent"; // Urgent, High, Neutral, Low
custom_data
Type: object
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
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
function
The on_open event is triggered when the Feedback button is clicked.
Userback.on_open = () => {
alert("open");
};
on_close
Type: function
function
The on_close event is triggered when the Close button is clicked
Userback.on_close = () => {
alert("close");
};
after_send
Type: function
function
The before_send event is triggered when the Send button is clicked
Userback.before_send = () => {
alert("before send");
};
before_send
Type: function
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
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
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
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
function
syntax: Userback.init('[Userback Widget Token]', '[Options]');
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:
name
,categories
, andpriority
Userback.init('[Userback Widget Token]', {
email: '[email protected]',
name: 'Someone Someone'
});
show()
type: function
function
The show method displays the Userback Widget.
Userback.show();
hide()
type: function
function
The hide method closes the Userback Widget interface and hides it.
Userback.hide();
open()
type: function
function
syntax: Userback.open('[Feedback_Type]', '[Destination]');
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
, andform
// 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
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
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
function
Note: Use
custom_data()
when the JavaScript SDK hasn't been added. Otherwise, usesetData()
(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 whensetData()
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.