Copy & paste Javascript Code Snippet

To launch Refiner surveys inside your application you need to install our JavaScript client snippet first. Installing the code snippet should only take a couple of minutes and you only need to do it once.

Basic installation

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>

Once done, replace the static value ‘REFINER_PROJECT_ID’ with the identifier of your Refiner project. You can find the identifier in your Refiner dashboard under “Settings > Installation”.

If you are currently logged in to your dashboard, the identifier should have already been replaced for you.

That’s it! You are ready to launch surveys and call-to-actions for your users.

The code snippet above operates Refiner in the “anonymous visitor mode”. It means that no personal information about your users is shared with Refiner. Once the user fills out a survey, their answers are stored but without a specific identifier or email address.

To get the most out of Refiner, we highly recommend to identify logged in users though as shown in the next chapter.

Identify users (recommended)

Refiner unleashes its full power when you identify your users and we highly recommend that you take the time to set up user identification.

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

Identifying a user is easy with our Javascript client. All you need to do is to call a identifyUser method once our Javascript client was loaded.

The identifyUser call expect a unique identifier (“user ID”) for each user. If you can’t provide a unique user ID for each user, please operate Refiner in anonymous visitor mode (see above).

The example from above then becomes:

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

Was this helpful?