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
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,
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
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.