Advanced JavaScript integration

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.

Identify users

If you are reading this guide, you are most likely already identifying your users in some way. 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',
  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 surveys ad-hoc

Sometimes you might want to show a form programmatically, directly from your application’s JavaScript code. 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);

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.

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

Attach data to survey 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