Developer's API Documentation

The Usersnap Track widget can be conveniently configured without any coding skills.

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

Configurations which are made through code always overwrite configurations made by the configurator.

If the configuration variable _usersnapconfig is used, it has to be set just before the widget is called.

An example code could look like:

<script type="text/javascript">
 var _usersnapconfig = {
     theme: "brownie"
 };
 (function() {
   var s = document.createElement("script");
   s.type = "text/javascript";
   s.async = true;
   s.src = '//api.usersnap.com/load/'+
        '[APIKEY].js';
   var x = document.getElementsByTagName('script')[0];
   x.parentNode.insertBefore(s, x);
 })();
</script>

Know when Usersnap Track has been loaded

To allow specific and controlled sequential initialization of your page, Usersnap Track provides a property called loadHandler. Provide a function, and it will be called immediately after the Usersnap Track 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>

General Events

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

Event
Action

load

Will be called after Usersnap Track is fully (async) loaded. See more
here.

beforeOpen

Will be called before the Usersnap Track 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 Track successfully. See more here.

beforeScreenshot

Will be called before the screenshot will be captured, use this event to hide private information.

error

Will be called if an error occurs. See more here.

cancel

Will be called if the Usersnap Track widget will be closed (e.g. cancel button clicked). See more here.

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

Example usage:

<script type="text/javascript">
 var _usersnapconfig = {
    loadHandler: function() {
       UserSnap.on('cancel', function() {
          console.log('Usersnap is canceled...');
       });
    }
 };
</script>

The best place to add the Usersnap Track event listeners is the loadHandler because at that moment Usersnap is available!

Detect errors (wrong API key, ...)

Usersnap Track 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 = {
    loadHandler: function() {
       UserSnap.on('error', 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 canceled (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 Track calls this handler if the user clicks on the cancel button or if the screen is resized after clicking on the Usersnap Track button with a type object.

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

Start Usersnap Track manually

If you want to start Usersnap Track with your own Javascript code you can simply use the API method UserSnap.start();. After that call, the widget will be started!

<script type="text/javascript">
  UserSnap.start();
</script>

Annotation Tools

Usersnap Track provides different tools which can be used to add annotations in the browser. By default, Usersnap Track 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 Track 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:

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

Both, the placeholder of the comment box and the email field in the Usersnap Track widget can be customized. Moreover, you can prefill the mailbox with your customer's email address. The individual properties are self-explanatory - here’s an example configuration:

<script type="text/javascript">
 var _usersnapconfig = {
     emailBoxPlaceholder: 'Your Email here.',
     commentBoxPlaceholder: 'Please enter your mood here.',
     emailBoxValue: 'user@mycompany.com'
 };
</script>

If you want to change the email field from your code there is an API call available for that UserSnap.setEmailBox('user@company.com');.

If you want to add a hidden email address, simply specify emailBox: false and use emailBoxValue: 'user@mycompany.com'. The other option is to set the value via the Javascript API UserSnap.setEmailBox('user@mycompany.com');.

Enable and configure the title field in the Usersnap Track 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.',
     titleValue: 'Predfined Title'
 };
</script>

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'],
       labelAllowCreate: false,
       labelMultiSelect: false
 };
</script>

If you want to set hidden labels, simply set label: false, but specify a labels: ['Bug'] array. This will set the labels but hide the UI.
If you don't want your users to be able to create new labels, you'll have to set labelAllowCreate: false.
For allowing to select only one label, set labelMultiSelect: false.

When Usersnap Track is started

The beforeOpen property can be used to provide a function which is called as soon as the Usersnap Track widget has started (e.g., click on the button or open it with our API).

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

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

Add custom information to your screens

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

This function takes an object as an 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 = {
     loadHandler: function() {
        UserSnap.on("beforeSend", function(obj) {
           obj.addInfo = 'Some User Information';
        });
     }
 };
</script>

You can also specify a complex object.

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

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

A screen is sent - get notification after a Usersnap screen is sent!

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

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

<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 Track button or hide the Usersnap Track button

In the widget configurator, you can change the setting to hide the default Usersnap Track button. To invoke Usersnap Track, you will have to call the Usersnap manually.

To launch Usersnap Track in this case, call
UserSnap.openReportWindow(); from your code. This way you can use any button you like to invoke Usersnap Track.

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.

Language support

The Usersnap Track widget supports 30 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>

English

lang: 'en'

Bulgarian

lang: 'bg'

Chinese (Simplified)

lang: 'zh'

Chinese (Traditional)

lang: 'zh-TW'

Croatian

lang: 'hr'

Czech

lang: 'cz'

Danish

lang: 'da'

Dutch

lang: 'nl'

Farsi

lang: 'fa'

Finnish

lang: 'fi'

French

lang: 'fr'

French (Canada)

lang: 'fr-CA'

German (formal)

lang: 'de-formal'

German (informal)

lang: 'de-informal'

Hungarian

lang: 'hu'

Icelandic

lang: 'is'

Italian

lang: 'it'

Japanese

lang: 'jp'

Korean

lang: 'ko'

Norwegian

lang: 'no'

Polish

lang: 'pl'

Portuguese

lang: 'pt'

Portuguese (Brazil)

lang: 'pt-BR'

Romanian

lang: 'ro'

Russian

lang: 'ru'

Slovak

lang: 'sk'

Spanish

lang: 'es'

Spanish (Latin America)

lang: 'es-LA'

Swedish

lang: 'sv'

Turkish

lang: 'tr'

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

Customize your widget by choosing a Theme

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

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

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

If you want to use Usersnap Track only for your QA team (or a restricted audience), it could be a good idea to hide the Usersnap Track 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.start()</span from your JavaScript code.

Hide the guided tour

Every time your users open Usersnap Track for the first time, a guided tour and a help window is displayed. If you don't want this window to be displayed by default, you can hide the initial tour window of Usersnap Track.

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.


Developer's API Documentation