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.<\/p>\n\n\n\n
Before you can use the JavaScript SDK 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 SDK can be installed in following ways:<\/p>\n\n\n\n
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<\/a>, creating target audiences<\/a>, etc.<\/p>\n\n\n\n The identifyUser<\/em> call expect a unique identifier (“user ID”) or an email address for each user. We recommend to provide both values if possible.<\/p>\n\n\n\n The identifyUser<\/em> method also lets you import additional user traits as described below.<\/p>\n\n\n\n Importing additional data points allows you to better segment and target<\/a> users in Refiner. <\/p>\n\n\n\n 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<\/em> call as shown below.<\/p>\n\n\n\n The following data types are supported:<\/p>\n\n\n\n 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.<\/p>\n\n\n\n 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, …).<\/p>\n\n\n\n Refiner has a couple of reserved fields<\/a> you should be aware of. These fields can’t be overwritten or have a certain behaviour attached to them.<\/p>\n\n\n\n You can also make use of Magic Variables<\/a> to dynamically inject certain client related values as described further below.<\/p>\n\n\n\n When using our centralized translation interface<\/a> or language targeting<\/a>, you can manually set the language of a user. If you don’t set the language, the preferred web-browser languages are used instead.<\/p>\n\n\n\n The expected format of the locale variable is a comma separated list of two characters ISO 639-1 codes<\/a>.<\/p>\n\n\n\n We recommend to call the setLocale<\/em> method right before the identifyUser<\/em> method.<\/p>\n\n\n\n As an alternative to the ‘setLocale’ method, it is also possible to provide a “locale” trait in an additional option object when identifying a user.<\/p>\n\n\n\n When using our country targeting<\/a> option, the country of a user is by default detected automatically using their IP address. You can choose to manually set the country of a user and thus deactivate the IP address lookup. <\/p>\n\n\n\n The expected format of the country variable is a two characters ISO 3166 country code<\/a>.<\/p>\n\n\n\n We recommend to call the setCountry<\/em> method right before the identifyUser<\/em> method.<\/p>\n\n\n\n As an alternative to the ‘setCountry’ method, you can also provide a “country” trait in an additional option object when identifying a user.<\/p>\n\n\n\n Tracking user events<\/a> with our SDK is easy. Once our JavaScript client was loaded and an identifyUser<\/em> call was performed, you can track events with a single line of code as shown above.<\/p>\n\n\n\n Please note that we are only tracking the occurrence of an event. It is not possible to attach attributes to an event.<\/p>\n\n\n\n The start time of the current user session can be used as the reference time in the Time Delay<\/a> and Tracked Event<\/a> survey trigger.<\/p>\n\n\n\n We try to automatically detect when a user starts a new session in your application. A new user session is detected when a user returns to your application after at least one hour of inactivity.<\/p>\n\n\n\n You can choose inform Refiner that a new session started with the startSession<\/em> method as shown below. You can call this method for example right after a user logs in to your application.<\/p>\n\n\n\n It’s possible to reset user identifiers that were set through the “identifyUser<\/a>” 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.<\/p>\n\n\n\n Please note: Resetting the user identity sets the client back into “Anonymous Mode<\/a>“. However, an anonymous local storage identifier<\/a> linked to the user will persist and our API will continue to recognize the user. 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<\/a>” command.<\/p>\n<\/div><\/div>\n\n\n\n Our Javascript client allows you to attach additional data to the survey responses.<\/p>\n\n\n\n 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. <\/p>\n\n\n\n To attach additional data to survey response, execute the following command including the data you want to attach before the survey is shown. <\/p>\n\n\n\n You can execute the command either on page load, or dynamically right before a survey is triggered, for example by leveraging the “onBeforeShow<\/a>” callback function.<\/p>\n\n\n\n You can also make use of Magic Variables<\/a> to dynamically inject certain client related values when survey responses are stored as described further below.<\/p>\n\n\n\n Please note that common information like the current URL, the user language, etc. can also be attached to survey responses using our built-in metadata collection<\/a> option.<\/p>\n\n\n\n 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. <\/p>\n\n\n\n To reset the attached data, execute the method and provide a null<\/em> value. You can use the “onComplete” callback to reset the data after a survey was submitted.<\/p>\n\n\n\n You can tag survey responses<\/a> programmatically using the tagResponse method. You can define up to ten tags that will be associated with all upcoming survey responses. <\/p>\n\n\n\n To reset tagging, you can set the tags to null<\/em>.<\/p>\n\n\n\n Sometimes you might want to show or hide a survey programmatically, directly from your application’s JavaScript code. The Manual survey trigger<\/a> allows you do exactly this.<\/p>\n\n\n\n Once the JavaScript client was loaded and an identifyUser call was performed, you can launch a survey with the code below.<\/p>\n\n\n\n The ID of your form can be found in the survey editor under “Targeting & Launch Behaviour > Trigger Event > Manually”<\/p>\n\n\n\n Please note:<\/em> The showForm function takes other trigger restriction into account and you might receive a “already completed” or similar messages.<\/p>\n\n\n\n To circumvent this, you can add an additional boolean parameter which then forces the survey view.<\/p>\n\n\n\n When it comes to hiding a survey programmatically, you can either call a closeForm<\/em> or dismissForm<\/em> method. Both methods close a survey immediately and there is no difference between the two from a user’s point of view. <\/p>\n\n\n\n There is however a difference in what kind of information is sent to our backend API. The method dismissForm<\/em> will ping our server and we’ll store a dismissed_at<\/em> timestamp for the user.<\/p>\n\n\n\n The closeForm<\/em> method won’t send any information to our server and just closes the survey silently. <\/p>\n\n\n\n Calling closeForm<\/em> and dismissForm<\/em> when no survey is visible at the time of calling has no effect. You can safely call the methods as a precaution mechanism to make sure that all surveys are closed at a certain time.<\/p>\n\n\n\n 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.<\/p>\n\n\n\n The following callback hooks are available:<\/p>\n\n\n\nIdentify users<\/h3>\n\n\n\n
_refiner('identifyUser', {\n id: 'USER-ID-ABC-123', \/\/ Replace with your user ID\n email: 'jane@awesome.com', \/\/ Replace with user Email\n name: 'Jane Doe'\n});\n<\/pre>\n\n\n\nImport user traits<\/h3>\n\n\n\n
_refiner('identifyUser', {\n id: 'USER-ID-ABC-123',\n name: 'Jane Doe',\n email: 'jane@awesome.com',\n signed_up_at: '2020-04-26T17:58:14+02:00',\n ...\n custom_user_data: 'Some important data',\n upgraded_at: '2021-05-05 17:12',\n a_number: 42,\n more_custom_user_data: 'Something even more important',\n ...\n});<\/pre>\n\n\n\n\n
Set user language<\/h3>\n\n\n\n
\/\/ set one preferred language\n_refiner('setLocale', 'fr');\n\n\/\/ it is also possible to set multiple preferred languages\n_refiner('setLocale', 'fr,en,es');<\/pre>\n\n\n\n_refiner('identifyUser', {\n id: 'your-user-id',\n a_trait: 'trait data'\n}, {\n locale: 'fr'\n});<\/pre>\n\n\n\nSet user country<\/h3>\n\n\n\n
_refiner('setCountry', 'fr');<\/pre>\n\n\n\n_refiner('identifyUser', {\n id: 'your-user-id',\n a_trait: 'trait data'\n}, {\n locale: 'fr',\n country: 'fr'\n});<\/pre>\n\n\n\nTrack events<\/h3>\n\n\n\n
_refiner('trackEvent', 'MyCustomEventName');<\/pre>\n\n\n\nStart new session<\/h3>\n\n\n\n
_refiner('startSession');<\/pre>\n\n\n\nReset users<\/h3>\n\n\n\n
_refiner('resetUser');<\/pre>\n\n\n\nAttach data to responses<\/h2>\n\n\n\n
Add hidden fields<\/h3>\n\n\n\n
_refiner('addToResponse', {\n more_data: \"Hello!\"\n});<\/pre>\n\n\n\n_refiner('onComplete', function(formId, responseData) {\n _refiner('addToResponse', null);\n});<\/pre>\n\n\n\nTag response<\/h3>\n\n\n\n
_refiner('tagResponse', ['tag1', 'tag2']);<\/pre>\n\n\n\n_refiner('tagResponse', null);<\/pre>\n\n\n\nShow and hide survey ad-hoc<\/h2>\n\n\n\n
Show survey<\/h3>\n\n\n\n
_refiner('showForm', 'SURVEY_ID');<\/pre>\n\n\n\n_refiner('showForm', 'SURVEY_ID', true);<\/pre>\n\n\n\nClose survey<\/h3>\n\n\n\n
_refiner('dismissForm');<\/pre>\n\n\n\n_refiner('closeForm');<\/pre>\n\n\n\nAdvanced options<\/h2>\n\n\n\n
Callback functions<\/h3>\n\n\n\n