Advanced JavaScript integration

Our quick installation already covered how to set up our JavaScript client to launch micro surveys within your SaaS app. In this guide we’ll dig deeper and cover advanced functions provided by the Refiner JavaScript client.

For completeness, let’s start with the basics again.

Install the JavaScript client

Include with <script> tag

Copy & paste the code shown below into your applications HTML code, ideally just before the </body> tag.

<script async src="https://js.refiner.io/v001/client.js"></script>
<script>
window._refinerQueue = window._refinerQueue || [];
function _refiner(){_refinerQueue.push(arguments);}
_refiner('setProject', 'REFINER_PROJECT_ID');  
</script>

Use NPM package

Alternatively, you can load our client with our NPM package.

npm install refiner.io
import _refiner from 'refiner-js';
_refiner('setProject', 'REFINER_PROJECT_ID');

Including the JavaScript client like shown in the code examples above is enough to launch surveys within your app.

However, all survey data will be submitted anonymously and you won’t be able to properly target your users.

We strongly recommend to identify logged in users as shown in the next section.

Identify users

Identifying your users allows you to better target specific accounts, sync survey responses with your user data, trigger user specific automations etc.

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.

<script async src="https://js.refiner.io/v001/client.js"></script>
<script>
window._refinerQueue = window._refinerQueue || [];
function _refiner(){_refinerQueue.push(arguments);}
_refiner('setProject', 'REFINER_PROJECT_ID');  // first we set the project ID
_refiner('identifyUser', {
  id: 'USER-ID-ABC-123', // The ID of your user
  email: 'jane@awesome.com', // Provide their email address (optional)
  name: 'Jane Doe', // The full name of the user (optional)
});
</script>

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”). You can tell Refiner to which account a user belongs by adding an account object in the identifyUser call. As with 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',
    ...
  }
});

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', 'ID-OF-FORM');

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

Our client allows you to programmatically attach additional data to the responses provided by the user.

A popular use-case for this function would be to track on which page a user filled out the form.

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