Install Refiner with our NPM Package

Our official NPM wrapper class provides a simple installation of the Refiner.io client through NPM.

The package automatically injects the Refiner.io JavaScript client and exports an object that wraps all client methods. All method calls are queued end executed once the Refiner.io JavaScript client is fully loaded.

Once installed, Popup Surveys and Call To Actions created through the Refiner dashboard are launched automatically according to their trigger configuration.

Installation

Our NPM package is installed in the same way you would install other packages. Navigate to the source code folder of your project and execute the following NPM installation command.

npm install refiner.io

Usage

Initialize client

The initialize the Refiner client you need to import our wrapper as shown below. This will give you a Refiner object which you can use to trigger all supported functions.

import Refiner from 'refiner-js';

Refiner('setProject', 'REFINER_PROJECT_ID');

Please make sure to replace the static value ‘REFINER_PROJECT_ID’ with your project ID. You can find your project ID in the your Refiner dashboard under “Settings > Installation”. In case you are connected to your Refiner dashboard right now, the code snippet above should already include your project ID.

That’s it! The Refiner JavaScript client is now loaded and communicating with the Refiner API. It’s time to identify your users.

Identify your 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 Javasript client was loaded.

Refiner('identifyUser', {
  id: 'USER-ID-ABC-123', // Each user needs an ID or email address
  email: 'jane@awesome.com', // Each user needs an ID or email address
  name: 'Jane Doe', // The full name of the user
});

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