Usersnap API

📘

Usersnap snippet code (global 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.

If you decide to install the project-specific widget code which limits the displaying functionalities, you have to use the different API code.

Installation

Usersnap lets you further customize your project widget. First, you would need your global API key, which can be found in the installation tab of the main navigation bar (team level, not project level).

Next, you'd need to install the widget with the following JavaScript code. Then, you can call API methods later in your code.

<script>
  window.onUsersnapCXLoad = function(api) {
    api.init();
    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>

Examples for installation on well-known frameworks

Check out sample code for installing widgets in different popular frameworks in the repository below.

Using API methods

init()

The init function initializes the API. It must be called before calling any other API method.

Params

  • options: object
  • options.custom: object – a object holding custom data
  • options.user: object – a object holding user information
  • options.user.email: string – the email of the user. Is used to determine whether to show a widget or not.
  • options.user.userId: any – the id of the user. Is used to determine whether to show a widget or not.

Returns : Promise<void>

init() can be used to set default values that will be submitted to Usersnap, as follows:

Setting default values when initializing the widget

api.init({
  custom: {
    applicationLanguage : "de",
  },
  user: {
    userId: "123",
    email: "[email protected]",
  },
});
  • "custom": Any custom data that should be passed along with the feedback
  • "user": User data from known users

The custom data will show up on your Usersnap dashboard as follows:

Show a feedback button

Shows the feedback button. Calling this method disables the display rules for this widget.

Params

  • apiKey: string – the API key of the project
  • config: object – a config object that is merged with the widget's actual config

Params

api.show('[PROJECT_API_KEY]')

Hide a feedback button

Hides the feedback button. Calling this method disables the display rules for this widget.

Params

  • apiKey: string – the API key of the project

Returns : Promise<void>

api.hide('[PROJECT_API_KEY]')

The feedback button of a certain project can be hidden/displayed independently via the API.
Just call those methods and pass the APIKEY of the according project.

Open a feedback widget

Show a widget via the API.

api.show('apiKey').then((widgetApi) => widgetApi.open())

Hide a feedback widget

Hide a widget via the API.

api.hide('apiKey').then((widgetApi) => widgetApi.open())

Destroy the API

Destroys the global API. You need to call init again before calling any other method.

Returns : Promise<void>

Passing user information via the API

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

// assuming a global widget config looking something like this
window.onUsersnapCXLoad = function(api) {
    api.init({
    user: {
      email: "[email protected]", // Email address
      userId: "USER_ID", // on client system
    }
  });
}

Trigger a Usersnap event

Triggers a Usersnap event that can be used to display the widget. It evaluates the display rules taking the last event into account.

Params

  • eventName: string – the event name

Returns : Promise<void>

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 display rules (Auto-Popup) 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;  // save the Usersnap widget 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>

<script>
  // function for triggering events from your code
  function triggerUsersnapEvent(eventName) {
    window.Usersnap && window.Usersnap.logEvent(eventName);
  }
  
  // i.e. if a button is clicked, execute this function
  triggerUsersnapEvent('button1clicked');
</script>

More related info here.

Updated 2 days ago



Usersnap API


Suggested Edits are limited on API Reference Pages

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