Refiner Client Reference

Introduction

Our Javascript web client exposes various methods that you can use to deeply integrate your web application or website with Refiner. On this page, we’ll cover each method and provide sample code 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 our 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'
});

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.

Import user traits

Importing additional data points allows you to better segment and target your 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 – 255 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.

For importing dates, we require you to add a “_at” to your attribute name. The JSON specification has no explizit way of declaring dates, and our API is detecting dates only if the attribute name ends with “_at” (e.g. created_at, upgraded_at, another_event_at, …).

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

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

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.

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.
  • onNavigation gets called when the user moves through the survey
  • 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('onNavigation', function(formId, formElement, progress) {
  console.log(formId);
  console.log(formElement);
  console.log(progress);
});

_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, responseData) {
  console.log('Survey ' + formId + ' was submitted');
  console.log(responseData);
});

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!",
  currentUrl: window.location.href
});

Set user language

When using our centralized translation interface, you can set the language of a user with the following method. As an alternative to this method, you can also provide a “locale” trait when identifying a user.

_refiner('setLocale', 'language-identifier');

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