API for Usersnap Classic projects (legacy)
Please, be aware that this API is only working in Usersnap Classic projects.
There are several ways how to add the Usersnap Classic widget code snippet in order to install the widget on your website.
If you intend on using the Usersnap API, it might be useful to install your widget in a way that the API is exposed.
window.onUsersnapLoad = function(api) {
api.init();
window.Usersnap = api;
}
var script = document.createElement('script');
script.async = 1;
script.src = 'https://api.usersnap.com/load/YOUR-API-KEY.js?onload=onUsersnapLoad';
document.getElementsByTagName('head')[0].appendChild(script);
By using the Usersnap Classic API you are able to configure your widget directly through the code, you can interact with the widget, like setting the placeholder text dynamically and you can also work with events.
Widget configuration
Coding skills are not required when configuring your Usersnap Classic widget in the widget settings of your dashboard.
Configuring your Usersnap Classic widget in your code offers you just a few more possibilities, such as setting the fields' placeholder text.
In general, the widget configuration is done in the init method. Please have a look at the following example.
<script>
window.onUsersnapLoad = function(api) {
api.init({
fields: {
comment: {
initialValue: 'Here could be a bug report template',
label: 'Your comment',
/* labels can also be defined multilingual:
label: {
de: 'Deine E-Mail Adresse',
en: 'Your E-mail address',
}
*/
required: true,
},
email: {
initialValue: '[email protected]',
label: 'E-Mail',
required: true,
},
},
});
}
</script>
<script src="//api.usersnap.com/load/YOUR-API-KEY.js?onload=onUsersnapLoad" async></script>
Configuring your widget offers you the possibility to
- Choose the widget color
- Choose the text, position, and existence of your feedback button
- Define which fields will be displayed and if they are required or optional
- Define which tools will be displayed
- Enable and configure the Console Recorder
- Set the language
- Define a shortcut that opens the widget
Widget Colors
You can choose a primary and a secondary color.
The primary color is the color of the feedback button and the main color of the widget on the header, the button and the frame that marks your screenshot area.
The secondary color is only visible on certain dialogs as the second button color.
window.onUsersnapLoad = function(api) {
api.init({
colors: {
primary: '#AFFE23',
secondary: '#AFFEEE',
},
});
}
Feedback Button
You can choose a text and position for your button, and if you want the icon to be displayed or not.
window.onUsersnapLoad = function(api) {
api.init({
button: {
icon: null,
label: 'button text',
position: 'bottomRight',
},
});
}
Possible values for the button position are
- "bottomRight"
- "rightCenter"
- "rightBottom"
- "bottomLeft"
- "leftCenter"
Creating A Custom Feedback Button
You can also hide the button. You can use this feature if you want users to use only a shortcut to open Usersnap or if you want to create your own custom button or open Usersnap via a menu.
window.onUsersnapLoad = function(api) {
api.init({
button: null
});
}
Widget Fields
There are five fields that can be displayed in the Usersnap widget and defined as required or optional.
- Title
- Comment
- Assignee
- Label
window.onUsersnapLoad = function(api) {
api.init({
fields: {
email: {
initialValue: '[email protected]',
label: 'E-Mail',
required: true,
},
title: {
initialValue: 'Predefined Title',
label: 'Title',
required: true,
},
comment: {
initialValue: 'Here could be a bug report template',
label: 'Your comment',
/* labels can also be defined multilingual:
label: {
de: 'Deine E-Mail Adresse',
en: 'Your E-mail address',
}
*/
required: true,
},
label: {
initialValue: 'feature',
label: 'Label',
required: true,
},
},
});
}
You can also hide widget fields.
window.onUsersnapLoad = function(api) {
api.init({
fields: {
email: null,
title: null,
comment: null,
assignee: null,
label: null
},
});
}
Widget Tools
You can set which tools and in what order to show them on the Usersnap Classic widget.
You can also define the colors for the widget tools.
window.onUsersnapLoad = function(api) {
api.init({
tools: {
keys: ['comment', 'pen', 'arrow', 'blackout'],
colors: ["#fb585b", "#3a21ce", "#4fcbc5", "#fdb64e"],
}
});
Console Recorder
You can turn on the console recorder and configure various settings via the code.
window.onUsersnapLoad = function(api) {
api.init({
consoleRecorder: true,
consoleRecorderCfg: {
maxMessages: 500, // default 50
maxExceptions: 500, // default 50
logObjectSize: 20480 // default 2048 bytes
},
});
}
Language Support
The Usersnap Classic widget supports the following languages:
English - 'en'
German - 'de'
French - 'fr'
Spanish - 'es'
Swedish - 'sv'
Dutch - 'nl'
Turkish - 'tr'
Italian - 'it'
You can set up your preferred language with the following configuration:
window.onUsersnapLoad = function(api) {
api.init({
locale: 'de',
});
}
Shortcut
If you want to use the Usersnap Classic widget only for your QA team (or a restricted audience), it is a good idea to hide the feedback button and enable the keyboard shortcut Ctrl+U.
If your users press Ctrl+U, Usersnap opens automatically.
window.onUsersnapLoad = function(api) {
api.init({
button: null,
shortcut: {
// values are directly compared with the javascript event
// availability depending on what the browser delivers
key: 'u', // compare case insensitive!
ctrlKey: true,
altKey: false,
},
});
}
Widget interaction
Via the Usersnap Classic API, it is possible to open the widget and to set the email or comment field dynamically.
To do so, make sure you add the snippet code with the API exposed.
window.onUsersnapLoad = function(api) {
api.init();
window.Usersnap = api;
}
var script = document.createElement('script');
script.async = 1;
script.src = 'https://api.usersnap.com/load/YOUR-API-KEY.js?onload=onUsersnapLoad';
document.getElementsByTagName('head')[0].appendChild(script);
Open the Widget
Usersnap.open();
Set the Email Field
To set the email field, you can either set the values already in the init() method or in the "open" event handler .
window.onUsersnapLoad = function(api) {
api.init({
fields: {
email: {
initialValue: "[email protected]",
label: "E-Mail",
required: true,
},
},
});
}
Event interaction
With the Usersnap Classic API it is possible to react to certain events, such as
- load
- open
- close
- submit
- error
Load Event
api.on("load", function(event) {…})
Open Event
api.on("open", function(event) {
event.api.setValue("email", "[email protected]");
event.api.setValue("comment", "As a … I want to …");
event.api.setValue("customData", "your individual data");
event.api.setValue("label", ["feature","improvement"]); //labels must already exist
})
Close Event
api.on("close", function(event) {})
Submit Event
api.on("submit", function(event) {
// event.sessionId - a temporary id, not the actual screen number
//With the sessionId, you can create a URL where you can later find the finished feedback
var url = "https://usersnap.com/a/#/company/pollscreen/" + event.sessionId;
})
Error Event
api.on("error", function(event) {})
Custom Data
Custom Data is the way to pass additional info along with your Usersnap screen.
You can use the following code sample to implement this feature.
Passing configuration when initializing the widget
api.init({
fields: {
customData: {
defaultValue: JSON.stringify({
name: 'companyname'
}),
},
},
}),
Setting the value on open event
api.on("open", function(event) {
event.api.setValue("customData", JSON.stringify({
Company: "Usersnap",
User: "Josef"
}));
});
Updated 4 months ago