📘
This is a technical documentation of the API
For more user-case oriented examples see Website inline form: API examples.

Installation

window.onUsersnapLoad = function(widgetApi) {
  widgetApi.init({ mountNode: document.getElementById('widgetContainer') });
}
var script = document.createElement('script');
script.defer = 1;
script.src = 'https://widget.usersnap.com/embed/load/<<PROJECT_API_KEY>>?onload=onUsersnapLoad';
document.getElementsByTagName('head')[0].appendChild(script);

API object

interface GlobalApi {
  init: (options: InitOptions) => void,
  on: (eventName: string, callback: (event: any) => void) => void,
  off: (eventName: string, callback: (event: any) => void) => void,
}

init()

api.init({
  mountNode: document.getElementById('widgetContainer')
  locale: 'de',
});

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

Params

options
options.mountNode – The container element in which the widget should appear
options.locale: string – Language in which widgets should be displayed
options.useSystemFonts: boolean – Can be used to disable loading external fonts. Defaults to false
options.useLocalStorage: boolean – Can be used to disable usage of localStorage. Defaults to true
options.nativeScreenshot: boolean – Can be used to enable the usage of the native screenshot feature. Defaults to false
options.collectGeoLocation: 'all' | 'none' – can be used to disable the collection of IP and geo location. Defaults to 'all'

Returns `Promise<void>`

on()

function handleSubmit() {
  console.log('Widget was submitted')
}
api.off('submit', handleSubmit)

Registers an event handler for widget events.
For a detailed list of available events and how they can be used see section Widget Events

Params

eventName: string – the name of the widget event you want to listen to
callback: (event: WidgetEvent) => void – callback to handle the event. The structure of the received object depends on the event.

Returns `void`

off()

api.off('submit', handleSubmit)

Removes an event handler

Params

eventName: string – the name of the widget event want to remove the listener from
callback: (event: WidgetEvent) => void – same callback that was used for registering the event

Returns `void`

Widget Events

open – A widget was opened.
beforeSubmit– Before form values are submitted
submit – After form values were submitted

`open` event

type ValueKey = 'assignee' | 'custom' | 'labels' | 'visitor'

interface OpenEvent {
  apiKey: string,
  api: {
    setValue: (key: ValueKey, value: any) => void,
  },
}

apiKey– API key of the widget that was opened
api.setValue – method to set form values

Example

function handleWidgetOpened(event) {
  // You can check whether a specific widget was called
  if (event.apiKey !== '<PROJECT_API_KEY>') return;
  
  // Set Assignee. A User with this email has to exist in your Usersnap account
  event.api.setValue('assignee', 'mail@example.test') 
  // Set custom data
  event.api.setValue('custom', { applicationLanguage : 'de' })
  // Set labels
  event.api.setValue('labels', ['bug', 'critical'])
  // Set email
  event.api.setValue('visitor', 'mail@example.test')
}
api.on('open', handleWidgetOpened)

`beforeSubmit` event

type ValueKey = 'assignee' | 'custom' | 'labels' | 'visitor'

interface BeforeSubmitEvent {
  apiKey: string,
  api: {
    setValue (key: ValueKey, value: any) => void,
  }
  values: {
    assignee?: string,
    custom?: any,
  	labels?: string,
    visitor: string,
  }
}

apiKey– API key of the widget that will be submitted
api.setValue – method to set form values. Allows changing values before they are submitted.
values – values that will be submitted

Example

function handleBeforeSubmit(event) {
  var labels = event.values.labels
  if (labels && labels.includes('bug')) {
  	event.api.setValue('assignee', 'mail@example.test')
  }
}
api.on('beforeSubmit', handleBeforeSubmit)

`submit` event

interface CloseEvent {
  apiKey: string,
}

apiKey– API key of the widget that was submitted

Example

function handleSubmit() {
  // do something
}
api.on('submit', handleSubmit)