API examples

Examples of how to use the API

Set a language via the API

Set the language when you initiate the Usersnap code snippet (locale: 'de').

Here are the official codes for each language (ISO-639-1-Codes).
(except for traditional (zh-TW) vs simplified (zh-CN) Chinese:

[ 'cs', 'de', 'en', 'es', 'fr', 'hr', 'hu', 'it', 'ja', 'ko', 'lt', 'nl', 'pl', 'ro', 'ru', 'sk', 'sv', 'tr', 'pt', 'zh-CN', 'zh-TW' ]

Place the correct language code into the "locale" variable:

<script>
  window.onUsersnapCXLoad = 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=onUsersnapCXLoad';
  document.getElementsByTagName('head')[0].appendChild(script);
</script>

Triggering a Usersnap event - example

You can trigger widgets to be opened if a certain Usersnap event is fired. This example shows you how to trigger a Usersnap event.

In the "Configuration" section > display rules, choose Auto-Popup and you can set the event name to which you want to show a feedback widget.

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

More related info here.

Click a link to open the feedback widget

Hide the feedback button in the dashboard by setting the audience to "Nobody". After the Usersnap widget is initialized in your website / web application (the snippet code is added), you can open the widget by using this code example.

<li class="nav-item"><a class="sidebar-link" href="javascript:window.Usersnap.open();"><span class="icon-holder"><i class="c-red-500 ti-share"></i> </span><span class="title">Click to trigger widget</span></a></li>

Set variables when the widget is opened (button clicked)

You have to install the Usersnap snippet code before. And don't forget to pass on the API to the global variable window.Usersnap for this example.

If you want to pass certain information to all your projects, once the widget is opened, you can add the code like this.

widgetApi.on('open', (event) => {
  console.log('setting value now!');
  event.api.setValue('visitor', '[email protected]');
  event.api.setValue('custom', { userId: '123', environment: 'staging' });
  event.api.setValue('labels', 'bug');
  event.api.setValue('assignee', '[email protected]');
  alert('now, values are set');
});

If you want to pass certain information only to a certain project, once the widget is opened, you can add the code like this.

window.Usersnap.show('[Project-API-key]').then((widgetApi) => {
  /* In here you can use the widgetApi as documented for the project snippet */

  widgetApi.on('open', (event) => {
        console.log('setting value now!');
        event.api.setValue('visitor', '[email protected]');
        event.api.setValue('custom', { userId: '123', environment: 'staging' });
        alert('now, values are set');
    });

});

Open a widget after after 5 seconds

This widget opens after 5 seconds and will not show again before 30 days.

<script>
    // set cookie
  function setCookie(name, value, seconds) {
      var date, expires;
      if (seconds) {
          date = new Date();
          date.setTime(date.getTime()+(seconds*1000));
          expires = "; expires="+date.toGMTString();
          
      } else {
          expires = "";
      }
      document.cookie = name+"="+value+expires+";secure";
  }
  
  // get cookie
  function getCookie(cname) {
        var name = cname + "=";
        var decodedCookie = decodeURIComponent(document.cookie);
        var ca = decodedCookie.split(';');
        for(var i = 0; i <ca.length; i++) {
          var c = ca[i];
          while (c.charAt(0) == ' ') {
            c = c.substring(1);
          }
          if (c.indexOf(name) == 0) {
         console.log('getCookie ' + c.substring(name.length, c.length));
           return c.substring(name.length, c.length);
          }
        }
        return "";
  }
  
  window.onUsersnapCXLoad = function(api) {
    api.init();
    window.Usersnap = api;
  }

  // open widget after 5 seconds
  var noopen = getCookie('noopen');
  console.log('getCookie ' + noopen);
  if (noopen !== 'true') { 
    setInterval(function() { window.Usersnap.open() }, 5000); }

  // set a cookie for 30 days to not show up again
  setCookie('noopen','true', 60*60*24*30);

  var script = document.createElement('script');
  script.defer = 1;
  /* no global, because the if clause must call the project specific project */
  script.src = 'https://widget.usersnap.com/load/[APIKey]?onload=onUsersnapCXLoad';
  document.getElementsByTagName('head')[0].appendChild(script);

</script>

Short notice: you can also use the auto-popup in the dashboard of Usersnap and set the time-on-page. No need to code there.

Open a feedback widget after a flow/process is finished

Let's assume you have a new flow in your application. After the process or flow is finished, your development team should just fire an Usersnap event and you can display a widget for it.

In the "Display Rules" section of your project (in the dashboard), set the configuration to "Auto Popup" and choose the trigger "API event". Add the name of the event. Here it's "new_payment_is_finished".

Eh voila, the feedback widget pops up after the process is finished.

<script>
window.Usersnap.logEvent('new_payment_is_finished');
</script>

Show the feedback widget after a user leaves the browser window (exit-intent)

This can be valuable to learn more about why your users are leaving your website or web application.

Currently, you need a bit of coding in JavaScript for that.

In this example, we use JQuery (a JavaScript library) to handle the exit-intent (leaving the browser window with the mouse).

<script src="https://d3e54v103j8qbb.cloudfront.net/js/jquery-3.4.1.min.220afd743d.js?site=5ad15d8c3265e9c49b438f4e" type="text/javascript" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script>
<script src="https://usersnapdemo.com/exitintent_website/jquery.exitintent.min.js"></script>

<script>

$.exitIntent('enable');

$(document).bind('exitintent', function() {
  // An intent to exit has happened
  //if (getCookie('widget_fired') != 'yes') {
      window.UsersnapCX.open();
      //setCookie('widget_fired','yes', 30);
  //}
});
     
window.onUsersnapCXLoad = function(api) {
  window.UsersnapCX = api;
  api.init();            
};
  
var script = document.createElement('script');
script.defer = 1;

// CHANGE - to your API key for Usersnap CX in the URL - IMPORTANT // ONLY EXIT INTENT
script.src = '//widget.usersnap.com/load/[APIkey]?onload=onUsersnapCXLoad&isdev=true';
document.getElementsByTagName('head')[0].appendChild(script);
                     
</script>

Send a widget request via email

Sometimes, it comes in handy, if you can send a request to your users to give you feedback via email. Let's say they complete a certain task in your application or finished a conversation with your customer service team. In this case, it's great if you can send a link to a feedback widget and collect the customer satisfaction rating (or any other feedback widget you like).

Using the full page collector for sending feedback requests via email

The easiest way to do that is our newly-released feature, we call it tenderly full page collector.

Using the Usersnap API to open a widget via a link in an email

However, if you feel a bit techier today, you can send a link to a page on your website and initiate a widget via Auto-Popup e.g. https://www.demowebsite.com/?emailtrigger=true ... One of our co-founders thinks he's a developer and build this example for you. 😀

The variable "emailtrigger=true" is only to avoid that the widget popups up on your start page, you only want to show it when your users are clicking on the link in your email. You define in the "Configuration" section in the "Display" tab that this widget should only be shown if the URL contains "?emailtrigger=true".

If you want to also hand over the email of the user, you can use the following Usersnap snippet code.

Let's assume this is your URL:
https://www.demowebsite.com/?emailtrigger=true&[email protected]

<script>
  window.onUsersnapCXLoad = function(api) {
    // this takes the email from the URL from the parameter "email"
    const queryString = window.location.search;
    const urlParams = new URLSearchParams(queryString);
    const email = urlParams.get('email');
    //only in case you also want to set a rating number
    //const rating = urlParams.get('rating');
    console.log(email);

    api.init({
      user: {
        email: email, // Email address
        // in case you want to set a rating via the URL parameters
        //rating: rating,
      }
    });
  }
  var script = document.createElement('script');
  script.defer = 1;
  script.src = 'https://widget.usersnap.com/global/load/[GLOBAL API KEY]?onload=onUsersnapCXLoad';
  document.getElementsByTagName('head')[0].appendChild(script);
</script>

Here's a video how it can look like

How to set a project to show as a feedback button and auto-popup on different pages?

Please first select the project's "Activation" to "Button" with "Audience" set to "Nobody".

And then please use the following snippet:

window.onUsersnapCXLoad = function (api) {
    api.init();
    window.Usersnap = api

    // to show the button for the widget
    window.Usersnap.show('[Project-Api-Key]')

    // to show the widget
    window.Usersnap
        .show('[Project-Api-Key]', { button: null })
        .then(widgetApi => widgetApi.open())
}
var script = document.createElement('script');
script.defer = 1;
script.src = 'https://widget.usersnap.com/global/load/[Global-Api-Key]?onload=onUsersnapCXLoad';
document.getElementsByTagName('head')[0].appendChild(script);

Updated 2 months ago


API examples


Suggested Edits are limited on API Reference Pages

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