Refiner Client Reference

In previous guides, we covered how to quickly install the Refiner client to launch your first survey. In this guide we’ll dig deeper into advanced functions provided by the Refiner JavaScript client.

We’ll assume that you successfully installed the Refiner client, either by copy & pasting our code snippet, with our NPM package or Google Tag Manager.

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 our client in anonymous mode, identifying your users will unlock many powerful features such as segmenting your users, creating target audiences, etc.

Below, we’ll cover in detail every aspect of identifying your users, from providing additional user traits to grouping users into accounts.

Identify your users with their ID or email address

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
});

Import additional user traits

Importing additional data points allows you to better segment and target your users in Refiner. Sending in additional traits is easy. Just add the traits you wish to appear in Refiner to 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',
  ...
});

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.

As with other user data, you can also provide additional account traits 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',
  more_custom_user_data: 'Something even more important',
  ...
  account: {
    id: 'ACCOUNT-ID-ABC-12345',
    name: 'Awesome Inc.',
    paying_customer: true,
    created_at: '2020-04-26T17:58:14+02:00',
    trial_ends_at: '2020-05-26T17:58:14+02:00',
    ...
    custom_account_data: 'Whatever is needed',
    ...
  }
});

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.

_refiner('resetUser');

Please note: Resetting the user identity sets the client back into “Anonymous Mode“. However, an anonymous cookie ID linked to the user will persist and our API will recognize the user based on the anonymous ID. 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

Sending user events to Refiner 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');

Show and hide survey ad-hoc

Sometimes you might want to show or hide a survey programmatically, directly from your application’s JavaScript code. Our client exposes methods to do exactly this.

Show survey programmatically

Once our 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.

A popular use-case for callback functions is to redirect a user to a new page once they completed a survey.

  • onBeforeShow gets called right before a survey is supposed to be shown.
  • onShow gets called when a survey widget becomes visible to your user.
  • onClose gets called when the survey widgets disappears from the screen.
  • onDismiss gets called when the user dismissed a survey by clicking on the “x” in the top right corner.
  • onComplete gets called when the user completed (submitted) a survey.

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');
  console.log(formConfig);
  if (formId === 'ABC') {
    console.log('Abort mission');
    return false;
  }
  console.log('Continue and show survey');
  next();
});

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

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

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

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

Add data to responses (Hidden fields)

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. All you need to do is to execute the following command including the data you want to attach.

_refiner('addToResponse', {
  moreData: "Hello!",
  anotherDataField: "Hello2"
});

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.

_refiner('stopPinging');

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