API for Usersnap Classic Project

🚧
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
E-mail
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"
  }));
});

Usersnap Help Center

How can we help?

API for Usersnap Classic Project