Web-Client Reference


Our Javascript web client exposes various methods that can be used to deeply integrate your web application with Refiner. On this page, we’ll cover each method and provide sample code which you can use for your project.

Install client

To make the installation process as easy as possible for you, we are offering different options depending on what technology you are familiar with. At the moment of writing, Refiner can be installed in following ways:

Identify users

Identifying your users is most likely the first thing you want to do once you’ve successfully installed our client. While it’s possible to operate the client in anonymous mode, identifying your users will unlock many powerful features such as segmenting your users, creating target audiences, etc.

Identify with User ID or Email

The identifyUser call expect a unique identifier (“user ID”) or an email address for each user. We recommend to provide both values if possible.

_refiner('identifyUser', {
    id: 'USER-ID-ABC-123', // Replace with your user ID
    email: 'jane@awesome.com', // Replace with user Email
    name: 'Jane Doe'

The identifyUser method also lets you import additional user traits as described below.

Import additional user traits

Importing additional data points allows you to better segment and target users in Refiner.

Sending in additional traits is easy. All you need to do is to include the traits you wish to appear in Refiner to in the identifyUser call as shown below.

_refiner('identifyUser', {
  id: 'USER-ID-ABC-123',
  name: 'Jane Doe',
  email: 'jane@awesome.com',
  signed_up_at: '2020-04-26T17:58:14+02:00',
  custom_user_data: 'Some important data',
  upgraded_at: '2021-05-05 17:12',
  a_number: 42,
  more_custom_user_data: 'Something even more important',

The following data types are supported:

  • Strings – 10.000 characters max length
  • Integer numbers – ranging from -2147483647 to 2147483647
  • Dates – ISO date format or Linux timestamp

To import an integer number, please make sure that the value is not wrapped in quotes. Wrapping a number in quotes will result in a String value in Refiner.

If you want to import dates, the identifier of your field needs to follow a certain pattern. As the JSON specification has no explicit way of declaring dates, we rely on the field identifier to determine if a value should be read as a date or a normal string. Our API is detecting dates if the attribute name ends with “_at” (e.g. created_at, upgraded_at, another_event_at, …) or “_date” (e.g. subscription_date, last_login_date, …).

Refiner has a couple of reserved fields you should be aware of. These fields can’t be overwritten or have a certain behaviour attached to them.

You can also make use of Magic Variables to dynamically inject certain client related values as described further below.

Provide Identity Verification signature

If you are using the option Identity Verification security mechanism, you can pass the computed signature in an additional object as shown below.

Please make sure that you are passing the signature and not the secret key.

_refiner('identifyUser', {
    id: 'USER-ID-ABC-123', // Replace with your user ID
    email: 'jane@awesome.com', // Replace with user Email
    name: 'Jane Doe'
}, {

If your app loads user data asynchronously, you can include the computed signature in the response from the server alongside other user data. Please make sure to always compute the signature on the backend and never client-side in the frontend code.

You can verify that the signature was computed correctly by opening the Developer Console of your web browser. If you see requests to our server failing with a 403 code, your signature is not calculated correctly.

Group users into accounts

Most B2B SaaS applications are running on an account based system, where multiple users are grouped under one account (think “Team Accounts”, “Organization”, or “Company”).

Refiner supports “N users = 1 account” relationships out of the box. You can tell Refiner to which account a user belongs by adding an account object in the identifyUser call.

You can also include account level data inside the account object (see above) in the same way you would for user level data.

_refiner('identifyUser', {
  id: 'USER-ID-ABC-123',
  email: 'jane@awesome.com',
  name: 'Jane Doe',
  account: {
    id: 'ACCOUNT-ID-ABC-12345',
    name: 'Awesome Inc.',
    some_account_data: 'something',
    a_date_at: '2022-01-31'

Please note: Refiner supports N:1 group relationships, where one user belongs to one group (company, account, …). If your app is running on an N:N relationship model where one user belongs to multiple groups, we recommend to keep things simple and work on a user level only.

Reset user identifiers

It’s possible to reset user identifiers that were set through the “identifyUser” command. If you are using Refiner in a Single Page Application (SPA), we recommend executing the following command after a user logs out from your app.


Please note: Resetting the user identity sets the client back into “Anonymous Mode“. However, an anonymous local storage identifier linked to the user will persist and our API will continue to recognize the user. You might still see an “last seen at” for the user even if they are logged out. To stop all communication with our servers, we recommend to also execute the “stopPinging” command.

Track user events

Tracking user events with our Web-Client is easy. Once our JavaScript client was loaded and an identifyUser call was performed, you can track events with a single line of code as shown above.

_refiner('trackEvent', 'MyCustomEventName');

Please note that we are only tracking the occurrence of an event. It is not possible to attach attributes to an event.

Tag response

You can tag survey responses programmatically using the tagResponse method. You can define up to ten tags that will be associated with all upcoming survey responses.

_refiner('tagResponse', ['tag1', 'tag2']);

To reset tagging, you can set the tags to null.

_refiner('tagResponse', null);

Show and hide survey ad-hoc

Sometimes you might want to show or hide a survey programmatically, directly from your application’s JavaScript code. The Manual survey trigger allows you do exactly this.

Show survey programmatically

Once the JavaScript client was loaded and an identifyUser call was performed, you can launch a survey with the code below.

The ID of your form can be found in the survey editor under “Targeting & Launch Behaviour  > Trigger Event > Manually”

_refiner('showForm', 'SURVEY_ID');

Please note: The showForm function takes other trigger restriction into account and you might receive a “already completed” or similar messages.

To circumvent this, you can add an additional boolean parameter which then forces the survey view.

_refiner('showForm', 'SURVEY_ID', true);

Close survey programmatically

When it comes to hiding a survey programmatically, you can either call a closeForm or dismissForm method. Both methods close a survey immediately and there is no difference between the two from a user’s point of view.

There is however a difference in what kind of information is sent to our backend API. The method dismissForm will ping our server and we’ll store a dismissed_at timestamp for the user.

_refiner('dismissForm', 'SURVEY_ID');

The closeForm method won’t send any information to our server and just closes the survey silently.

_refiner('closeForm', 'SURVEY_ID');

Register callback functions

Registering callback functions allows you to execute any JavaScript code at specific moments in the lifecycle of a survey. For example, redirect a user to a new page once they completed a survey.

The following callback hooks are available:

onBeforeShowGets called right before a survey is supposed to be shown.
onCloseGets called when the survey widgets disappears from the screen.
onCompleteGets called when the user completed (submitted) the entire survey.
onDismissGets called when the user dismissed a survey by clicking on the “x” in the top right corner.
onErrorGets called when a request from the client to our backend API fails.
onNavigationGets called for each step when the user responds to questions or navigates through the survey.
onRequestResponseGets called whenever the client receives a response from the backend API.
onShowGets called when a survey widget becomes visible to your user.

Registering callback functions is done as shown in the code example below.

_refiner('onBeforeShow', function(formId, formConfig, next) {
  console.log('Survey ' + formId + ' is supposed to be shown');
  if (formId === 'ABC') {
    console.log('Abort mission');
    return false;
  console.log('Continue and show survey');

_refiner('onClose', function(formId) {
 console.log('Survey ' + formId + ' was closed');

_refiner('onComplete', function(formId, responseData) {
  console.log('Survey ' + formId + ' was submitted');

_refiner('onDismiss', function(formId) {
 console.log('Survey ' + formId + ' was dismissed');

_refiner('onNavigation', function(formId, formElement, progress) {

_refiner('onRequestResponse', function(httpCode, functionName, responseData) {

_refiner('onShow', function(formId) {
  console.log('Survey ' + formId + ' was shown');

Add data to responses

Our Javascript client allows you to attach additional data to the survey responses. A popular use-case for this function would be to track on which page a user filled out the form.

Attaching data to your survey responses is like a hidden field feature in traditional survey tools. However, you don’t need to create a field in your Refiner dashboard.

To attach additional data to survey response, execute the following command including the data you want to attach before the survey is shown.

_refiner('addToResponse', {
  more_data: "Hello!",
  current_url: '__CURRENT_URL__'

You can execute the command either on page load, or dynamically right before a survey is triggered, for example by leveraging the “onBeforeShow” callback function.

You can also make use of Magic Variables to dynamically inject certain client related values when survey responses are stored as described further below.

The provided data is persistent throughout all upcoming survey responses that happen until the page is reloaded. If you expect additional survey responses to which you don’t want to attach the additional data, you can reset the data or overwrite it with different data.

To reset the attached data, execute the method and provide a null value. You can use the “onComplete” callback to reset the data after a survey was submitted.

_refiner('onComplete', function(formId, responseData) {
  _refiner('addToResponse', null);

Add data to user

If you want to add traits to a user object, we usually recommend to user identifyUser method as described above. As an alternative, you can also provide user traits through the addToUser method.

The main difference between the two methods is that identifyUser creates a user profile in Refiner immediately when the web-client is loaded. The method addToUser does not create a user profile immediately. Traits are kept locally und are sent to Refiner when a survey is shown to the user.

Unlike the identifyUser method, no user identifier (ID or email) is required for the addToUser method. You can use this method to add user traits when you are operating the web-client in anonymous user mode. If you choose to provide a “id” or “email” trait, it will be interpreted as a user identifier.

_refiner('addToUser', {
    a_user_traits: 'something',
    another_user_trait: 'something else',

Set user language

When using our centralized translation interface or language targeting, you can manually set the language of a user. If you don’t set the language, the preferred web-browser languages are used instead.

The expected format of the locale variable is a comma separated list of two characters ISO 639-1 codes.

We recommend to call the setLocale method right before the identifyUser method.

// set one preferred language
_refiner('setLocale', 'fr');

// it is also possible to set multiple preferred languages
_refiner('setLocale', 'fr,en,es');

As an alternative to the ‘setLocale’ method, it is also possible to provide a “locale” trait in an additional option object when identifying a user.

_refiner('identifyUser', {
  id: 'your-user-id',
  a_trait: 'trait data'
}, {
  locale: 'fr'

Set user country

When using our country targeting option, the country of a user is by default detected automatically using their IP address. You can choose to manually set the country of a user and thus deactivate the IP address lookup.

The expected format of the locale variable is a two characters ISO 3166 country code.

We recommend to call the setCountry method right before the identifyUser method.

_refiner('setCountry', 'fr');

As an alternative to the ‘setCountry’ method, you can also provide a “country” trait in an additional option object when identifying a user.

_refiner('identifyUser', {
  id: 'your-user-id',
  a_trait: 'trait data'
}, {
  locale: 'fr',
  country: 'fr'

Magic Variables

Magic Variables allow you to add contextual data to survey responses or user profiles without needing to code any Javascript. You can use Magic Variables to store things like the URL, information about a user’s web browser, or their IP address alongside survey responses.

Magic Variables can be used when identifying a user or attaching data to survey responses as shown in the code sample below.

_refiner('identifyUser', {
  id: 'USER-ID-ABC-123',
  country_code: '__COUNTRY__',

_refiner('addToResponse', {
  url: '__CURRENT_URL__',
  browser_name: '__WEB_BROWSER__',

Here is the list of all Magic Variables supported by the Refiner Web-Client:

__COUNTRY_CODE__The country code of the user as described here
__CURRENT_URL__The current URL of the user
__IP_ADDRESS__The current IP address of the user
__LOCALE__The locale value as described here
__WEB_BROWSER__The web browser name of the user (e.g. Chrome 27)
__WEB_DEVICE_OS__The operating system of the user (e.g. Mac OS)
__WEB_DEVICE_TYPE__The device type of the user (e.g. desktop, tablet, mobile)

Disable client

Calling the following command will instruct our client to stop query our servers for new information. You can call this command for example after a user logs out of your app. Ad-hoc commands that are launched by your code (e.g. trackEvent or showForm) will still get executed.


Set client to Dark-Mode

If your application has a “dark mode”, our survey widget might show an opaque background in some browsers. It is a known issue that iframes are using opaque background when the color scheme of an HTML document is set to dark-mode and we are working on a permanent fix for this issue.For a quick solution, please add the following CSS to your application code when in dark mode:

#refiner-widget-frame { color-scheme: light; }

Was this helpful? Let us know with a quick a vote