Skip to main content
With the script tag, the API is on window.Usertick; with the npm package, it is the default export. The script tag defines Usertick before the full runtime loads, and calls made in that time are queued and run in order once it loads.

​
init

Starts the widget: loads the site’s code file with its live surveys, checks each survey’s rules and arms the triggers of the surveys that match. Only the npm package needs it, because the script tag starts the widget by itself.
​
string
required
The site ID from Settings → Sites, which is also the file name in the site’s install code. The widget shows surveys only on that site’s domain and its subdomains.
A second call logs a warning and does nothing. To start again, call destroy first. Where there is no window, as in server rendering, init does nothing.

​
on / off

on subscribes to a widget event (open, close, submit or error) and returns a function that removes the handler. off removes a handler. Handlers added before the widget is ready are attached when it becomes ready.

​
trigger

Sends a custom event. A live survey on the current page whose Custom event trigger has the same name opens, if its other rules allow it.
​
string
required
The name the survey’s trigger listens for. The match ignores upper and lower case and spaces around the name.
​
object
The event’s properties. A trigger with property rules opens only when every rule holds for them (plan is pro, total is at least 100), and nested values are reachable with dotted keys such as order.total. A key matches exactly first, then in any case. A trigger without rules ignores the payload.
The widget keeps the last 50 events. An event sent before the widget is ready is checked against the surveys for 10 seconds after it becomes ready, and a later event for 10 seconds after it was sent, so a survey whose trigger starts a little later, for example after a route change, still sees it. An event that opened a survey never opens that survey again.

​
identify

Tells the widget who the visitor is. On the page, the sign-in state and trait rules in Targeting read it, and every survey on the page is checked again at once, so a survey for plan is pro can open on the same page right after sign-in. When the visitor submits a response, it carries a respondent block with the user ID, the traits, the hash and an anonymous ID for this browser. Nothing is sent before Submit, and nothing is sent when the site’s Send user identity with responses switch is off or the survey has Anonymous responses on. See Identify your users.
​
string | null | undefined
required
Your user ID, up to 256 characters. null works like logout. undefined keeps the stored ID and only updates the traits. An ID different from the stored one starts with no traits and no hash.
​
object
A flat map of strings, numbers and booleans: up to 50 keys of at most 64 characters, with strings of at most 256 characters. A trait past these limits is dropped with a console warning. Later calls merge into earlier ones. email, name and company become the respondent’s email, name and company.
​
string | null
The user hash your server computes, which proves the user ID: the HMAC-SHA256 of the user ID with the organization’s identity secret key, as 64 hex characters. It never expires. null drops a stored hash, and a value that isn’t 64 hex characters is dropped with a console warning. See Verify your users.

​
logout

Signals that the user signed out. The widget forgets the ID, the traits and the hash, creates a new anonymous ID and checks every survey again. The next response carries only the new anonymous ID, so the next person on a shared device is never merged into this user. The display history is kept, so a survey that was already answered doesn’t come back. While nobody is signed in, logout() keeps the anonymous ID, so the call is safe on every anonymous page load.

​
show / hide

show opens a survey without waiting for its trigger. It brings back the popup on screen or minimized, or else opens the side button’s survey. Otherwise, it opens the highest-priority survey that passes every other rule on the page, including the repeat behavior, and logs a console message when none does. hide closes the open popup; with no popup open, it hides the minimized popup or the side button. Embedded surveys stay on the page. show is the usual way to test a survey without waiting for its trigger.

​
reset

Clears what the widget remembers in this browser: the display history (cooldowns, shown-once and submitted flags), the visit counters, the anonymous ID and the identify record with its hash. Responses waiting to be sent are kept. Use it while testing a survey that doesn’t appear again; to sign a user out, use logout.

​
destroy

Removes every survey card, listener and queued custom event from the page. A later init starts fresh, so handlers added with on need to be added again. In a single page app, call it from the cleanup of the component that called init.

​
Survey selection

Every live survey that passes its page rules, devices, targeting and repeat behavior arms its trigger. The first popup trigger to fire opens its survey, and the other popups wait. Only one popup shows at a time. After it closes, the others are armed again and can still open under their own trigger and repeat behavior. A side button and an embedded survey take places of their own, so they never hold a popup back. Surveys are checked again after a route change in a single page app and after identify.