Website widget (button, pop-up): API examples

For a technical reference of the Javascript API, see Website widget API.

📘

Usersnap global code snippet REQUIRED

Please, be aware that this API needs the standard Usersnap snippet code (the global snippet). This snippet is a code you or your developer have to install once and then, you can decide which feedback widget should be displayed on what pages. The following API examples are ONLY for the standard Usersnap snippet installations.

Set the widget language

When initializing the JS API you can pass a language as ISO-639-1-Code.
Here are the codes for each supported language:

  • cs (Czech)
  • de (German)
  • en (English)
  • fr (French)
  • hr (Croatian)
  • hu (Hungarian)
  • it (Italian)
  • ja(Japanese)
  • ko (Korean)
  • lt (Lithuanian)
  • nl (Dutch)
  • pl (Polish)
  • pt (Portuguese)
  • ro (Romanian)
  • ru (Russian)
  • sk (Slovak)
  • sv (Slovenian)
  • tr (Turkish)
  • zh-TW (Chinese - traditional)
  • zh-CH (Chinese - simplified)

The desired code can be passed in form of the locale parameter:

<script>
  window.onUsersnapLoad = function(api) {
    api.init({ locale: 'de' })
    window.Usersnap = api;
  }
  var script = document.createElement('script');
  script.defer = 1;
  script.src = 'https://widget.usersnap.com/global/load/<GLOBAL_API_KEY>?onload=onUsersnapLoad';
  document.getElementsByTagName('head')[0].appendChild(script);
</script>

Passing user information

You can pass user information to Usersnap to increase the options to target specific user groups and provide targeted experiences.

At the moment we support two parameter:

  • email: The email will be pre-filled in the widget.
    If no email field is configured, it still will be stored with the feedback
  • userId: If a userId is passed, the user counts as "logged in user" for targeting purposes.
    The ID is not stored.
<script>
  window.onUsersnapLoad = function(api) {
    api.init({ 
      user: {
        email: '[email protected]',
        userId: 'USER_ID',
      }
    })
    window.Usersnap = api;
  }
  var script = document.createElement('script');
  script.defer = 1;
  script.src = 'https://widget.usersnap.com/global/load/<GLOBAL_API_KEY>?onload=onUsersnapLoad';
  document.getElementsByTagName('head')[0].appendChild(script);
</script>

If you want to store more user data, you can pass it as custom data.

Passing custom data

You can pass any data you like in the form of custom data to the widget. This data will be stored with every submitted feedback item.
There are two options to achieve this.

Option 1: When initializing the widget

<script>
  window.onUsersnapLoad = function(api) {
    api.init({ 
      custom: {
        appVersion: '1.0.1',
        environment: 'production',
      }
    })
    window.Usersnap = api;
  }
  var script = document.createElement('script');
  script.defer = 1;
  script.src = 'https://widget.usersnap.com/global/load/<GLOBAL_API_KEY>?onload=onUsersnapLoad';
  document.getElementsByTagName('head')[0].appendChild(script);
</script>

Option 2: On opening the widget

You can choose this option e.g. if you want to pass data that is only available after loading Usersnap.

<script>
  // Step 1: Initialize Usersnap 
  window.onUsersnapLoad = function(api) {
    api.init()
    
    // Step 2: Register an event handler on open
    api.on('open', function(event) {
      event.api.setValue('custom', {
        appVersion: '1.0.1',
        environment: 'production',
      })
    })
  }
  var script = document.createElement('script');
  script.defer = 1;
  script.src = 'https://widget.usersnap.com/global/load/<GLOBAL_API_KEY>?onload=onUsersnapLoad';
  document.getElementsByTagName('head')[0].appendChild(script);
</script>

Pre-fill the widget with information

Apart from custom data you can also set the assignee, labels and the email of the user when opening the widget.

<script>
  // Step 1: Initialize Usersnap 
  window.onUsersnapLoad = function(api) {
    api.init()
    
    // Step 2: Register an event handler on open
    api.on('open', function(event) {
      // Set Assignee. A User with this email has to exist in your Usersnap account
      event.api.setValue('assignee', '[email protected]')
      // Set labels
      event.api.setValue('labels', ['bug', 'critical'])
      // Set email
      event.api.setValue('visitor', '[email protected]')
    })
  }
  var script = document.createElement('script');
  script.defer = 1;
  script.src = 'https://widget.usersnap.com/global/load/<GLOBAL_API_KEY>?onload=onUsersnapLoad';
  document.getElementsByTagName('head')[0].appendChild(script);
</script>

All those values will be visible and editable for the user if the respective field is available in the widget's form.

Trigger a widget from code (custom feedback button)

You can trigger widgets from code by calling api.logEvent(). This call can be embedded in any logic you can come up with.
E.g. after a successful checkout or when your code detects an error on the page.

First, setup a widget to open up when a specific event is logged:

  1. Go to your project's "Configuration" page -> "Targeting" tab.
  2. Look for "Trigger & frequency" section of "Targeting" tab.
    For "Select how you would like to activate this widget" choose "API event". (See screenshot below)
  3. In "Event" field enter your desired event name e.g. my-awesome-event (do not use quotes) and make sure to hit the "Save" button on the bottom of the page.

Your project needs to be set live (top right corner of page).

In your code you simply call api.logEvent('my-awesome-event') whenever you want to open the widget.
The following code showcases this with the implementation of a custom feedback button.

<button type="button" id="feedbackButton">
  Give Feedback
</button>
<script>
  // step 1: initialize the global snippet and make Usersnap API available
  window.onUsersnapLoad = function(api) {
    api.init();
    // step 2: add event handler to button
    var button = document.getElementById("feedbackButton");
    button.addEventListener("click", function() {
      // step 3: call logEvent
      api.logEvent("my-awesome-event");
    }); 
  }
  var script = document.createElement('script');
  script.defer = 1;
  script.src = 'https://widget.usersnap.com/global/load/YOUR-GLOBAL-APIKEY?onload=onUsersnapLoad';
  document.getElementsByTagName('head')[0].appendChild(script);
</script>

Edit form values before they are submitted

Sometimes you want to edit or add form values before the feedback is created. This can be done by hooking into the beforeSubmit event. The following example sets the assignee to "[email protected]" in case the label "bug" was selected.

<script>
  // Step 1: Initialize Usersnap 
  window.onUsersnapLoad = function(api) {
    api.init()
    
    // Step 2: Register an event handler on beforeSubmit
    api.on('beforeSubmit', function(event) {
      // Step 3: Check if the label 'bug' was selected
      var labels = event.values.labels
      if (labels && labels.includes('bug')) {
        // Step 4: Set the assignee
        event.api.setValue('assignee', '[email protected]')
      }
  }
  var script = document.createElement('script');
  script.defer = 1;
  script.src = 'https://widget.usersnap.com/global/load/<GLOBAL_API_KEY>?onload=onUsersnapLoad';
  document.getElementsByTagName('head')[0].appendChild(script);
</script>

Deactivate tracking of location and IP

If you don't want Usersnap to track the IP and location (country, city) of the users, you can deactivate this by initiating the snippet code with the parameter collectGeoLocation: 'none'.

<script>
  window.onUsersnapLoad = function(api) {
    api.init({
        collectGeoLocation: 'none'
    });
    window.Usersnap = api;
  }
  var script = document.createElement('script');
  script.defer = 1;
  script.src = 'https://widget.usersnap.com/global/load/[GLOBAL_API_KEY]?onload=onUsersnapLoad';
  document.getElementsByTagName('head')[0].appendChild(script);
</script>

For any further questions, please contact our lovely customer success team.

Deactivate localStorage (Cookies)

The Usersnap feedback widgets do not use cookies, but we use the localStorage to store a few parameters. From a data privacy standpoint (GDPR), the localStorage is seen similar to cookies. If you want to deactivate the localStorage for your website or web application, you can do this with the following parameters.

Please, be aware that this has a few disadvantages for your users. For example, the email is not remembered for the next time, they give feedback. Also, the assignees are not stored.

<script>
  window.onUsersnapLoad = function(api) {
    api.init({
        useLocalStorage: false
    });
    window.Usersnap = api;
  }
  var script = document.createElement('script');
  script.defer = 1;
  script.src = 'https://widget.usersnap.com/global/load/[GLOBAL_API_KEY]?onload=onUsersnapLoad';
  document.getElementsByTagName('head')[0].appendChild(script);
</script>

Deactivate GoogleFonts

The Usersnap feedback widgets use GoogleFonts to make the widgets look nicer. If you don't want to use GoogleFonts, you can deactivate them by setting useSystemFonts to false.

<script>
  window.onUsersnapLoad = function(api) {
    api.init({
        useSystemFonts: false
    });
    window.Usersnap = api;
  }
  var script = document.createElement('script');
  script.defer = 1;
  script.src = 'https://widget.usersnap.com/global/load/[GLOBAL_API_KEY]?onload=onUsersnapLoad';
  document.getElementsByTagName('head')[0].appendChild(script);
</script>

Did this page help you?