Help Center

Developer API and Documentation

The Usersnap widget can be conveniently configured using the Usersnap Configurator which may cover a lot of use cases. The Usersnap Configurator can be used without any coding skills.

In addition to it, the Usersnap Widget can be configured using the Javascript API described below (some coding skills required - we’re happy to help).

The position of the Usersnap button

You can set up the vertical and the horizontal position of the Usersnap button by setting valign (allowed values are ‘bottom’ and ‘middle’) and halign (‘left’ or ‘right’)

<script type="text/javascript">
 var _usersnapconfig = {
     valign: 'bottom',
     halign: 'right'
 };
</script>

Language support

Usersnap currently supports 21 different languages. You can set up your preferred language with the configuration option lang as shown below.

<script type="text/javascript">
 var _usersnapconfig = {
     lang: 'de-informal'
 };
</script>
Language Language
English lang: 'en' German (informal) lang: 'de-informal'
German (formal) lang: 'de-formal' French lang: 'fr'
Spanish lang: 'es' Polish lang: 'pl'
Farsi lang: 'fa' Icelandic lang: 'is'
Japanese lang: 'jp' Italian lang: 'it'
Hungarian lang: 'hu' Korean lang: 'ko'
Czech lang: 'cz' Danish lang: 'da'
Norwegian lang: 'no' Slovakian lang: 'sk'
Dutch lang: 'nl' Swedish lang: 'sv'
Portuguese lang: 'pt' Finnish lang: 'fi'
Russian lang: 'ru' Turkish lang: 'tr'

If you want to change your language later with a Javascript function call, simply use: UserSnap.setLanguage('en'); This examples changes the language to english!

General Events

The UserSnap object has some general events on which you can listen.

Event Action
load Will be called after Usersnap is fully (async) loaded. See more here
beforeOpen Will be called before the Usersnap widget is opened. See more here
beforeSend Will be called right before the Usersnap screen will be submitted, you can add custom information here. See more here
afterSend Will be called after the screen has been submitted to Usersnap successfully.
beforeScreenshot Will be called before the screenshot will be captured, use this event to hide private information.

To listen on one of that events please use the method UserSnap.on(eventName, method).
Example usage:

<script type="text/javascript">
 UserSnap.on('load', function() {
   console.log('Usersnap is loaded...');
 });
</script>

Detect errors (wrong API key, ...)

Usersnap needs a correct API key to work properly. If it happens that you could configure a wrong API key or any other error occurs, you can detect such errors by writing an errorHandler callback.
Please use the errorCode parameter for handling different error types.

errorHandler gets called with at least two arguments:

  • errorMessage
  • errorCode
  • serverErrorCodes [optional]
<script type="text/javascript">
 var _usersnapconfig = {
     errorHandler: function(errorMessage, errorCode) {
        console.log("Error Code: " + errorCode);
        console.log("Error Message: " + errorMessage);
     }
 };
</script>
Error Code Error Message
100 Invalid API Key
101 Local Development not supported
102 Server error
103 Browser not supported yet
104 No configuration available
105 Communication error

Detect if a report was cancelled

If you want to know if a report has been cancelled (i.e. your user clicked the cancel button or the browser window was resized after clicking on the feedback button), you need to implement the cancelHandler callback.
Usersnap calls this handler if the user clicks on the cancel button or if the screen is resized after clicking on the feedback button with a type object.

{
    "type": "cancel" // (or "resize")
}
                
<script type="text/javascript">
 var _usersnapconfig = {
     cancelHandler: function(typeObj) {
        console.log("Report creation canceled: " + typeObj.type);
     }
 };
</script>

Alternatively, you can set this method with UserSnap.on():

<script type="text/javascript">
 var _usersnapconfig = {
     loadHandler: function() {
           UserSnap.on("cancelHandler",
              function(typeObj) {
                 console.log("Report creation cancelled: "+typeObj.type);
           });
     }
 };
</script>

Change the Usersnap button text

If you want to change the button text which (default is "Feedback") you can configure your own text by adding the btnText property to your configuration object.

<script type="text/javascript">
 var _usersnapconfig = {
     btnText: 'Help?'
 };
</script>

Annotation Tools

Usersnap provides different tools which can be used to add annotations in the browser. By default Usersnap will add all available tools but you can specify your own set of desired annotation tools by using the tools parameter.

Following tools are available and described in detail below:

  • Highlight "highlight"
  • Blackout "blackout"
  • Note "note"
  • Pen "pen"
  • Arrow "arrow"
  • Pixel Ruler "pixelruler"
  • Comment "comment"

Simply add your required tools in an array in the Usersnap configuration object. The following example uses the pen, the blackout and the note tool:

<script type="text/javascript">
 var _usersnapconfig = {
     tools: ['pen', 'blackout', 'note']
 };
</script>

The tools parameter follows the order you've specified in the tools array.
The example above will look like:

Different Usersnap annotation tools.

Set up the Comment Box and the Email Field in the Usersnap Widget

Both, the comment box and the email field in the Usersnap widget can be hidden or shown as desired. Moreover, the placeholder text can be adjusted and it’s also possible to set both fields to mandatory: that means your commenters need to enter their email address and a comment. The individual properties are self-explanatory - here’s an example configuration:

<script type="text/javascript">
 var _usersnapconfig = {
     emailBox: true,
     emailRequired: true,
     commentBox: true,
     commentRequired: true
     commentBoxPlaceholder: 'Please enter your mood here.',
     emailBoxValue: 'user@mycompany.com'
 };
</script>
Customized comment box!

Enable and configure the title field in the Usersnap Widget

Add an additional field which allows your customers to enter a title for the current screenshot. Optionally, you can define the title field as required or add a placeholder for it.

<script type="text/javascript">
 var _usersnapconfig = {
     title: true,
     titleRequired: true,
     titlePlaceholder: 'Please enter your title here.'
 };
</script>

Enable the console recorder

Enable the console recorder to track all XHR requests or javascript errors occurring in the browser.

XMLHttpRequest logging comes with every report, allowing your development team to know what actually happens when a user clicks on a button and it doesn't work. It's like giving your developers direct access to the Matrix.

<script type="text/javascript">
 var _usersnapconfig = {
     consoleRecorder: true
 };
</script>

Your visitors don't care about javascript errors, but your developers do. We record JavaScript errors as they happened, along with a host of other information needed for super-faster bug reproduction and debugging.

Assign your Usersnap screenshots to a default assignee

If you want that your customer can define an assignee you can enable the assignee field. By providing an email address you can easily assign screenshots to a specific person. Optionally, you can define the assignee field as required or add a placeholder for it.

<script type="text/javascript">
 var _usersnapconfig = {
     assignee: true,
     assigneeRequired: True,
     assigneePlaceholder: 'assignee@mycompany.com'
     
 };
</script>

Tag your Usersnap screenshots with labels

Enabling label allows your customers to tag your Usersnap screenshots. You can also define a default set of labels by providing a list of labels.

<script type="text/javascript">
 var _usersnapconfig = {
     label: true,
     labelRequired: true,
     labelPlaceholder: 'Feedback',
     labels: ['Feedback', 'Bug']
     
 };
</script>

Customize your widget by choosing a Theme

This option allows you to choose between custom themes provided by Usersnap. You can find a list of available themes here.

<script type="text/javascript">
 var _usersnapconfig = {
     theme: "Usersnap Blue"
 };
</script>

Know when Usersnap has been loaded

To allow specific and controlled sequential initialization of your page, Usersnap provides a property called loadHandler. Provide a function and it will be called immediately after the Usersnap widget is loaded.

An example code could look like:

<script type="text/javascript">
 var _usersnapconfig = {
     loadHandler: function() {
        alert('Usersnap widget now loaded!'); //some init code here.
     }
 };
</script>

Acting on the Usersnap button click

The beforeOpen property can be used to provide a function which is called as soon as the Usersnap button has been clicked.

For example, if you want to prefill the email field, your code would look like:

<script type="text/javascript">
 var _usersnapconfig = {
     beforeOpen: function(obj) {
        UserSnap.setEmailBox('mail@example.com');
     }
 };
</script>

Alternatively, you can set this function with UserSnap.on(). Make sure to call UserSnap.on() after Usersnap has been successfully loaded.

<script type="text/javascript">
 var _usersnapconfig = {
     loadHandler: function() {
     	UserSnap.on("beforeOpen", function() {
           UserSnap.setEmailBox('mail@example.com');
     	});
     }
 };
</script>

Add more information to your feedbacks

If you want to append specific additional information (such as the currently logged in user on your website) to your report, Usersnap's API provides an event to fetch those data right before the feedback is sent:beforeSend.

This function takes an object as argument where you can store all your required information - there is no restriction regarding the type or the structure of the passed object.

<script type="text/javascript">
 var _usersnapconfig = {
     beforeSend: function(obj) {
     	obj.addInfo = 'Some User Information';
     }
 };
</script>

You can also specify a complex object.

<script type="text/javascript">
 var _usersnapconfig = {
     beforeSend: function(obj) {
     	obj.addInfo = {
           companyName: 'Usersnap',
           username: 'Josef'
    	};
     }
 };
</script>

You can find the additional information at the detail page of your screen.

change the title of your project

Alternatively, you can set this method with UserSnap.on():

<script type="text/javascript">
 var _usersnapconfig = {
     loadHandler: function() {
        UserSnap.on("beforeSend", function(obj) {
           obj.addInfo = {
	          companyName: 'Usersnap',
	          username: 'Josef'
           };
        });
     }
 };
</script>

Waiting for successful report submission

If you want to know how if you report submission was successful you can use the afterSend handler.

Usersnap calls this handler with one parameter which represents the report id.

<script type="text/javascript">
 var _usersnapconfig = {
    afterSend: function(reportId) {
       console.log("My Report ID is: "+reportId);
    });
 };
</script>

Alternatively, you can set this method with UserSnap.on():

<script type="text/javascript">
 var _usersnapconfig = {
     loadHandler: function() {
        UserSnap.on("afterSend", function(reportId) {
           console.log("My Report ID is: "+reportId);
        });
     }
 };
</script>

Use a custom Usersnap button or hide the Usersnap button

By using the config option mode: 'report' Usersnap will not display the default button. To invoke Usersnap, you will have to call the Usersnap manually. To launch Usersnap in this case, call UserSnap.openReportWindow(); from your code. This way you can use any button you like to invoke Usersnap.

Here is an example:

<a href="#" onclick="UserSnap.openReportWindow();">Launch Usersnap</a>
<script type="text/javascript">
 var _usersnapconfig = {
     mode: 'report'
 };
</script>

Use a keyboard shortcut (Ctrl+U) to open Usersnap

If you want to use Usersnap only for your QA team (or a restricted audience), it could be a good idea to hide the Usersnap button (Please see Hide the default feedback button) and enable the keyboard shortcut Ctrl+U.

If your users press Ctrl+U Usersnap is opened automatically.

You can enable the keyboard shortcut with the shortcut option:

<script type="text/javascript">
 var _usersnapconfig = {
     shortcut: true
 };
</script>

If you want to hide the button and use the keyboard shortcut, take this configuration:

<script type="text/javascript">
 var _usersnapconfig = {
     mode: 'report',
     shortcut: true
 };
</script>

If you want to use any other key than U, you can add the keyboard handler for yourself (the jquery.hotkeys plugin may help you) and call UserSnap.openReportWindow() from your JavaScript code.

Hide the guided tour

Everytime your users open Usersnap for the first time, a guided tour and a help window is being displayed. If you don't want this window to show up per default, you can hide the initial tour window of Usersnap.

Please set the hideTour option to true:

<script type="text/javascript">
 var _usersnapconfig = {
     hideTour: true
 };
</script>

The tour and help window is still available for your users by clicking the help button.

We are using cookies to help make this website better. More details can be found in our Privacy Policy. Got it, do not show this message again.