Usersnap Help Center

API for Usersnap Classic (NEW) Widget

There are several ways how to add the Usersnap 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 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: {
          defaultValue: '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: {
          defaultValue: 'user@mycompany.com',
          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"

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 four fields that can be displayed in the Usersnap widget and defined as required or optional.

  • E-mail
  • Title
  • Comment
  • Assignee
  • Label
window.onUsersnapLoad = function(api) {
  api.init({
    fields: {          
      email: {
        defaultValue: 'user@mycompany.com',
        label: 'E-Mail',
        required: true,
      },      
      title: {
        defaultValue: 'Predefined Title',
        label: 'Title',
        required: true,
      },
      comment: {
        defaultValue: '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,
      },    
      assignee: {
        defaultValue: 'assignee@mycompany.com',
        label: 'Assignee',
        required: true,
      },
      label: {
        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 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 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 Usersnap Classic 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 is opened 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 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

For the "old" classic widget there was a separate API call "SetEmailBox()". This has changed with our new widget. 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: {
          defaultValue: "user@mycompany.com",
          label: "E-Mail",
          required: true,
        },      
      },
    });
  }

Event interaction

With the Usersnap 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", "john@doe.me");
  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"
  }));
});

API for Usersnap Classic (NEW) Widget

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.