Contact us! Start free trial!

Configure the Usersnap widget

Extended API Features

Installing the Usersnap snippet

Usersnap is a JavaScript code snippet which only needs to be copied into your web page, just before the closing </body> tag on your page. Most websites re-use one file for common content (so called templates), so it's very likely that you won't have to place the code snippet manually on every single page. If you don't know how to do this, please ask your website admin.

You can configure the look and feel of the Usersnap Widget using the Usersnap Configurator.

<script type="text/javascript">
var _usersnapconfig = {
        valign: 'bottom',
        halign: 'right',
        tools: ["pen", "highlight", "note"],
        lang: 'en',
        commentBox: true,
        emailBox: true
}; 
(function() {
    var s = document.createElement('script');
    s.type = 'text/javascript';
    s.async = true;
    s.src = '//api.usersnap.com/load/YOUR-APIKEY-HERE.js';
    var x = document.getElementsByTagName('head')[0];
    x.appendChild(s);
})();
</script>

The global configuration variable _usersnapconfig is used to configure Usersnap.
You can use the Configurator to change nearly all settings without changing your JavaScript code.

Please find a description of all configuration options below!

Adjusting the position of the Usersnap button

The Usersnap configuration allows you to configure the placement of the feedback button.
You can set up the vertical and the horizontal position of the Usersnap button.
The default configuration is valign: 'bottom', halign: 'right'.

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

Language support

Usersnap currently supports 21 different languages.
You can set up your preferred language with the configuration option lang as shown below. Click on the language for a demo!

   <script type="text/javascript">
     var _usersnapconfig = {
         lang: 'de-informal'
     };
   </script>

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!

Customize button text

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

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

We strongly recommend to check if your text fits to the button box.
The example above will look like:

tools

Tools

Usersnap provides five different tools which your visitors can use to add annotations to their current screen. By default (i.e. no tools parameter specified in the configuration object), Usersnap will add the highlighting tool, the blackout tool and the note tool, but you can specify your own set of tools by using the tools parameter.
Following tools are available and described in detail below:

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:

tools


highlight Highlight

The highlight tool may be used to indicate important areas on the page. The created highlighted areas can be easily removed by clicking the [X] icon in the upper right corner.

highlight
highlight

blackout Blackout

Your users can black out private areas on your page with a black rectangle. If you want to remove a blackened area you can easily remove by clicking the [X] icon in the upper right corner.

blackout
blackout

note Note

With the note tool you can put detailed information to the screenshot. Use it like you would use a sticky note on paper. You can move the sticky note with drag and drop and remove the note using the [X] icon in the upper right corner.

note
note

pen Pen

The pen tool allows you to make free annotations on your website. You can remove the line by using the [X] icon when you are near the line.

pen
pen

arrow Arrow

The arrow tool enables you to point out specific parts of the website. You can remove the arrow by using the [X] icon when you are near the arrow.

arrow
arrow

Add a comment box to the Usersnap widget

If you'd like to get general comments from your visitors, simply add commentBox: true to your Usersnap configuration snippet. You get a comment box right in the Usersnap widget. This settings can be combined with emailBox (see below).

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

Additionally you can specify the place-holder text of the comment box:

   <script type="text/javascript">
     var _usersnapconfig = {
         commentBox: true,
         commentBoxPlaceholder: 'Enter something special here.'
     };
   </script>

If you want to make the comment box necessary for a report, you can require it from your users:

   <script type="text/javascript">
     var _usersnapconfig = {
         commentBox: true,
         commentRequired: true
     };
   </script>
comment comment

Add an email field to the Usersnap widget

You can add an email field to allow your visitors to provide an email address to get back to them. If you set up Usersnap to receive your feedbacks via email, you can simply hit reply in your email client to respond to feedbacks. To enable it, add emailBox: true to your config. You can combine emailBox with commentBox.

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

Again you can specify your custom place-holder text:

   <script type="text/javascript">
     var _usersnapconfig = {
         emailBox: true,
         emailBoxPlaceholder: 'your company email address'
     };
   </script>

If you want to pre-fill the email address field, simply specify the emailBoxValue in your Usersnap configuration:

   <script type="text/javascript">
     var _usersnapconfig = {
         emailBox: true,
         emailBoxValue: 'user@mycompany.com'
     };
   </script>

The email address field can be also changed by a javascript call: UserSnap.setEmailBox('newaddress@mycompany.com'); sets the emailBoxValue to the given email address.

If you want to make the email address field necessary for a report, you can require it from your users:

   <script type="text/javascript">
     var _usersnapconfig = {
         emailBox: true,
         emailRequired: true
     };
   </script>
emailbox emailbox

It is possible to combine all described properties:

   <script type="text/javascript">
     var _usersnapconfig = {
         emailBox: true,
         commentBox: true,
         commentBoxPlaceholder: 'Enter something special here.',
         emailBoxValue: 'user@mycompany.com'
     };
   </script>
email and comment

Do some initialization

Sometimes you want to do some initialization stuff after loading the Usersnap widget code. For this needs we have prepared the loadHandler function. This function will be called 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!');
         }
     };
   </script>

Handle Usersnap Feedback button click

If you want to listen on the Usersnap button click, simply add a beforeOpen function. This event occurs exactly when the user clicks on the Usersnap feedback button. The Usersnap report window will be opened immediately. You can suspend your application and resume it later on or you can change properties like the user's email adress using the UserSnap.setEmailBox() function.

An example code could look like:

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

Alternatively, you can set this method 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 custom information to your feedbacks

If you want to append custom information (such as the currently logged in user of your website) to your report, Usersnap's API provides an event to fetch those data 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 type or structure of this 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>

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>

Get the report id after sending

If you want to know how you can identify your report after it has been sent, you need to implement an afterSend handler.
Usersnap calls this handler if the report has been sent successfully with the report id. You can use this id to identify your report, for example if you are using the HTTP-Push connection.

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

You can save this reportId via an AJAX call for example.


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>

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>

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]
List of error codes
Error Message Code
Invalid API Key 100
Local Development not supported 101
Server error 102
Browser not supported yet 103
No configuration available 104
communication error 105
   <script type="text/javascript">
     var _usersnapconfig = {
         errorHandler: function(errorMessage, errorCode) { 
            console.log("Error Code: " + errorCode);
            console.log("Error Message: " + errorMessage); 
         }
     };
   </script>

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

   <script type="text/javascript">
     var _usersnapconfig = {
         loadHandler: function() {
            UserSnap.on("errorHandler",
               function(errorMessage, errorCode) {
                 console.log("Error Code: " + errorCode);
                 console.log("Error Message: " + errorMessage);  
         	});
         }
     };
   </script>

Hide the default feedback button

If you want to use your own feedback button you can configure Usersnap without a button. By using the config option mode: 'report' Usersnap will not display a feedback button by default. To invoke Usersnap, you will have to call the feedback method manually.
To open the feedback dialog, call UserSnap.openReportWindow(); from your code. This way you can use any button you like to invoke Usersnap.

   <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 initial tour window

Everytime your users open Usersnap for the first time, an initial tour and help window is 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 when they click on the help button.
















Login
Chat with us!
×

Hey, I'm Josef!

May I help you?

Start Chat