The JavaScript API lets you programmatically customize various aspects of the Userback Widget in just a few lines of code.

Check out the Userback Developer Docs for a more in-depth look at this feature..


Enable the JavaScript API for triggering the widget

Note: Using the API for User Identification does not require you to enable this setting.

Note: Using the API for User Identification does not require you to enable this setting.

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.

  1. Open the "Targeting" section.

  2. Select the "Do not show the widget" option.

  3. Click Save changes.


Install the Widget Code

Add the following code to the web page where you would like the widget to be displayed. Replace the "[your widget token]" with your widget token which can be found here in your Widget Settings.

Method 1: Embed code:

When using embed code, the widget button is created on page load.

<script>
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);
</script>

Method 2: Script tag:

When using script tag, the widget button is created on calling init() method. This is the preferred option for single page apps.

<head>
<script src="https://static.userback.io/widget/v1.js"></script>
</head>

<body>
<script>
Userback.init('[your widget token]', {
email: 'aross@example.com',
name: 'Adriane Ross',
on_load: () => {
console.log('widget is loaded');
}
});
</script>
</body>

Install via official npm package

npm install @userback/widget or yarn add @userback/widget

https://www.npmjs.com/package/@userback/widget


Install in React

npm install @userback/react or yarn add @userback/react

https://www.npmjs.com/package/@userback/react

Install in Vue

npm install @userback/vue or yarn add @userback/vue

https://www.npmjs.com/package/@userback/vue


API Methods

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

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:

en:

English

da:

Danish

de:

German

es:

Spanish

et:

Estonia

fi:

Finnish

fr:

French

hu:

Hungarian

it:

Italian

jp:

Japanese

ko:

Korean

lt:

Lithuanian

pl:

Polish

pt:

Portuguese

pt-br

Portuguese (Brazil)

nl:

Dutch

no:

Norwegian

ro:

Romanian

ru:

Russian

sk:

Slovak

sv:

Swedish

zh-CN:

Simplified Chinese

zh-TW:

Traditional Chinese

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>


FAQ πŸ’¬

How do I access or enable the JavaScript API?

The JavaScript API is available on our Company Plan and above. There's no setup required, start adding your code and you're away! Compare Plans | Upgrade Now

This is really hard, can I have some help with this?

We get it! Feel free to message our team directly via Live Chat or Email and we'll be more than happy to assist.


πŸ” Who is this article for?

Plans

Solo

Startup

Company βœ”

Premium βœ”

User type

Client

Collaborator

Admin βœ”

Owner βœ”

Did this answer your question?