Web-Client Reference

Introduction

Our Javascript web client exposes various methods that can be used to deeply integrate your web application with Refiner. On this page, we’ll cover each method and provide sample code which you can use for your project.

Before you can use the web-client and its method, you’ll need to install it in your web application or on your website. To make the installation process as easy as possible for you, we are offering different options depending on what technology you are familiar with. The web-client can be installed in following ways:

• Copy & paste code snippet
• Google Tag Manager
• NPM Package
• WordPress Plugin

Identify & track 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 the client in anonymous mode, identifying your users will unlock many powerful features such as segmenting your users, creating target audiences, etc.

Identify users

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

The identifyUser method also lets you import additional user traits as described below.

Import user traits

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

If you want to import dates, the identifier of your field needs to follow a certain pattern. As the JSON specification has no explicit way of declaring dates, we rely on the field identifier to determine if a value should be read as a date or a normal string. Our API is detecting dates if the attribute name ends with “_at” (e.g. created_at, upgraded_at, another_event_at, …) or “_date” (e.g. subscription_date, last_login_date, …).

Refiner has a couple of reserved fields you should be aware of. These fields can’t be overwritten or have a certain behaviour attached to them.

You can also make use of Magic Variables to dynamically inject certain client related values as described further below.

// set one preferred language
_refiner('setLocale', 'fr');

// it is also possible to set multiple preferred languages
_refiner('setLocale', 'fr,en,es');

_refiner('identifyUser', {
  id: 'your-user-id',
  a_trait: 'trait data'
}, {
  locale: 'fr'
});

_refiner('setCountry', 'fr');

_refiner('identifyUser', {
  id: 'your-user-id',
  a_trait: 'trait data'
}, {
  locale: 'fr',
  country: 'fr'
});

_refiner('trackEvent', 'MyCustomEventName');

_refiner('startSession');

_refiner('resetUser');

Attach data to responses

Add 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.

To attach additional data to survey response, execute the following command including the data you want to attach before the survey is shown.

_refiner('addToResponse', {
  more_data: "Hello!",
  current_url: '__CURRENT_URL__'
});

You can execute the command either on page load, or dynamically right before a survey is triggered, for example by leveraging the “onBeforeShow” callback function.

You can also make use of Magic Variables to dynamically inject certain client related values when survey responses are stored as described further below.

The provided data is persistent throughout all upcoming survey responses that happen until the page is reloaded. If you expect additional survey responses to which you don’t want to attach the additional data, you can reset the data or overwrite it with different data.

To reset the attached data, execute the method and provide a null value. You can use the “onComplete” callback to reset the data after a survey was submitted.

_refiner('onComplete', function(formId, responseData) {
  _refiner('addToResponse', null);
});

Tag response

You can tag survey responses programmatically using the tagResponse method. You can define up to ten tags that will be associated with all upcoming survey responses.

_refiner('tagResponse', ['tag1', 'tag2']);

To reset tagging, you can set the tags to null.

_refiner('tagResponse', null);

Show and hide survey ad-hoc

Sometimes you might want to show or hide a survey programmatically, directly from your application’s JavaScript code. The Manual survey trigger allows you do exactly this.

Show survey

Once the 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

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

Advanced Options

Callback functions

Registering callback functions allows you to execute any JavaScript code at specific moments in the lifecycle of a survey. For example, redirect a user to a new page once they completed a survey.

The following callback hooks are available:

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('onClose', function(formId) {
 console.log('Survey ' + formId + ' was closed');
});

_refiner('onComplete', function(formId, responseData) {
  console.log('Survey ' + formId + ' was submitted');
  console.log(responseData);
});

_refiner('onDismiss', function(formId) {
 console.log('Survey ' + formId + ' was dismissed');
});

_refiner('onNavigation', function(formId, formElement, progress) {
  console.log(formId);
  console.log(formElement);
  console.log(progress);
});

_refiner('onRequestResponse', function(httpCode, functionName, responseData) {
  console.log(httpCode);
  console.log(functionName);
  console.log(responseData);
});

_refiner('onShow', function(formId) {
  console.log('Survey ' + formId + ' was shown');
});

Magic Variables

Magic Variables allow you to add contextual data to survey responses or user profiles without needing to code any Javascript. You can use Magic Variables to store things like the URL, information about a user’s web browser, or their IP address alongside survey responses.

Magic Variables can be used when identifying a user or attaching data to survey responses as shown in the code sample below.

_refiner('identifyUser', {
  id: 'USER-ID-ABC-123',
  country_code: '__COUNTRY__',
});

_refiner('addToResponse', {
  url: '__CURRENT_URL__',
  browser_name: '__WEB_BROWSER__',
});

Here is the list of all Magic Variables supported by the Refiner Web-Client:

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

Group users

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.

Verify identity

If you are using the option Identity Verification security mechanism, you can pass the computed signature in an additional object as shown below.

Please make sure that you are passing the signature and not the secret key.

_refiner('identifyUser', {
    id: 'USER-ID-ABC-123', // Replace with your user ID
    email: 'jane@awesome.com', // Replace with user Email
    name: 'Jane Doe'
}, {
    signature: COMPUTED_SIGNATURE
});

If your app loads user data asynchronously, you can include the computed signature in the response from the server alongside other user data. Please make sure to always compute the signature on the backend and never client-side in the frontend code.

You can verify that the signature was computed correctly by opening the Developer Console of your web browser. If you see requests to our server failing with a 403 code, your signature is not calculated correctly.

Enable Dark-Mode

If your application has a “dark mode”, our survey widget might show an opaque background in some browsers. It is a known issue that iframes are using opaque background when the color scheme of an HTML document is set to dark-mode and we are working on a permanent fix for this issue.For a quick solution, please add the following CSS to your application code when in dark mode:

#refiner-widget-frame { color-scheme: light; }

Deferred user identification

If you want to add traits to a user object, we usually recommend to user identifyUser method as described above. As an alternative, you can also provide user traits through the addToUser method.

The main difference between the two methods is that identifyUser creates a user profile in Refiner immediately when the web-client is loaded. The method addToUser does not create a user profile immediately. Traits are kept locally und are sent to Refiner when a survey is shown to the user.

Unlike the identifyUser method, no user identifier (ID or email) is required for the addToUser method. You can use this method to add user traits when you are operating the web-client in anonymous user mode. If you choose to provide a “id” or “email” trait, it will be interpreted as a user identifier.

_refiner('addToUser', {
    a_user_traits: 'something',
    another_user_trait: 'something else',
});