Introduction

The Expoints pop-up offers a variety of functionalities available to website developers who wish to integrate with Expoints to provide feedback forms on their website. These can be shown as pop-ups, pop-ins or inline feedback questionnaires.

Contact your Expoints experience manager. If you have none, mail to service@expoints.nl.

Implementation

The Expoints pop-up is easy to implement. After setting the options together with your Experience Manager, all you need to do is add a script to your website (this script will be provided by your Experience Manager), preferably at the bottom of the body. An example of the script is shown below. 
 <script type="text/javascript">
    (function() {
        var exp = document.createElement('script');
        exp.type = 'text/javascript';
        exp.async = true;
        exp.onload = function() {
            window.expoints = lightningjs.require('expoints','https:///<customer#>.expoints.nl/m/Scripts/dist/expoints-external.min.js');
            expoints('start', '737b2b78-a026-4774-b9d7-3321b3791fa4', { instanceUrl: 'https://<customer#>.expoints.nl' });
        };
        exp.src = 'https:///<customer#>.expoints.nl/m/Scripts/dist/expoints-external-loader.min.js';
        var s = document.getElementsByTagName('script')[0];
        s.parentNode.insertBefore(exp, s);
    })();
</script>

There are 2 options to trigger the pop-up on your website:

  1. Triggers managed within Expoints
  2. Manually (i.e. JavaScript, Google Tag Manager, ...)
Options are explained below.

Content Security Policy (CSP)

Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks, including Cross-Site Scripting (XSS) and data injection attacks. These attacks are used for everything from data theft, to site defacement, to malware distribution. (more info)

If your CSP header is configured incorrectly you might see an error similar to the one below:

Adjusting your CSP header

Using the following configuration as an example (the most strict): 
default-src 'self';
The minimal configuration to allow is (replace #customer with the correct URL): 
connect-src https://#customer.expoints.nl;
frame-src https://#customer.expoints.nl;
font-src https://#customer.expoints.nl https://cdn.expoints.nl;
img-src https://#customer.expoints.nl;
script-src 'self' https://#customer.expoints.nl;
style-src https://#customer.expoints.nl" />

Triggers managed within Expoints

After implementing the script on the main page you can set the requirements for each pop-up to trigger together with your Experience Manager. Within the Expoints platform we’ll set which questionnaire form (pop-up, pop-in, inline) is triggered by which target. Among others the following targeting options are available;
  • Current URL consists of, starts with, or is …;
  • Last URL consists of, starts with, or is …;
  • Device type is mobile, desktop or tablet;
  • Chance (for example 1 in 10)
  • Date
  • Etc.
Within these targets there are multiple operators possible (=,≠, contains, doesn’t contain). It is possible to combine these different targets.

Manually

To trigger the pop-up manually with JavaScript or in your own tag manager, e.g. Google Tag Manager (with JavaScript), implement the script as shown above. You can now trigger the questionnaire through a function in which you need to provided an agreed key with your Experience Manager. For example: 
expoints.trigger('manual_trigger_key');

Callback function

Before you are able to manually trigger the pop-up, our script first has to be fully loaded. This is done through an external library that loads the scripts asynchronously in a separate iFrame. A callback function can be provided to the start function: 
expoints('start', '737b2b78-a026-4774-b9d7-3321b3791fa4', { instanceUrl: 'https://.expoints.nl' },  callback);

function callback() {
    expoints.trigger('manual_trigger_key');
}

Inline

The inline questionnaire works with a selector that tells the code where to place the questionnaire. This selector can be a class or id of an element on the page and has to be a valid selector, for example: #ExpointsInlineSelector. Note: this selector needs to configured by the Experience Manager in the options.

Overriding the configured selector

If desirable it is possible to trigger the inline questionnaire manually with a specific selector. You can do so by running the following code: 
expoints.trigger('manual_trigger_key', null, 'override_selector')

OR

var data = [
    { id: 5, value: 'extern' }, 
    { id: 7, value: 'proces' }
];

expoints.trigger('manual_trigger_key', data, 'override_selector');
Note: the data is optional (see more below).

Settings extra data

This data will be included in future triggered pop-ups. Note that this only has an effect on pop-ups triggered after calling this function. 
var data = [
    { id: 5, value: 'extern' }, 
    { id: 7, value: 'proces' }
];

expoints.setCustomerData(data, (optional) configId);
In the code above you see an id and a value. Expoints data for a customers is set in so called customer data columns, these values represent them. The configId is a optional parameter, see below for further explanation. Discuss those with your experience manager before implementing.

To reset the data, call the following function: 
expoints.resetCustomerData((optional) configId);
The configId is a optional parameter, see below for further explanation.

Providing extra data on manual trigger

When manually triggering the pop-up, optional (extra) data can be provided to the trigger function as the second parameter. 
var data = [
    { id: 5, value: 'extern' }, 
    { id: 7, value: 'proces' }
];

expoints.trigger('manual_trigger_key', data);

Multiple configurations

The pop-up offers the ability to configure multiple configuration for one website.

For example, you have 2 instances of Expoints, one hosted on https://customer1.expoints.nl and one on https://customer2.expoints.nl. Our scripts can only be loaded from one of these instances as the 'main' library. Therefor the configuration of the second instance has to be loaded different from what is described above.

See the example below how to load a second configuration from a difference Expoints instance: 

 <script type="text/javascript">
    (function() {
        var exp = document.createElement('script');
        exp.type = 'text/javascript';
        exp.async = true;
        exp.onload = function() {
            window.expoints = lightningjs.require('expoints','https:///<customer#>.expoints.nl/m/Scripts/dist/expoints-external.min.js');
            expoints('start', '737b2b78-a026-4774-b9d7-3321b3791fa4', { instanceUrl: 'https://customer1.expoints.nl' }, loadSecondConfiguration);
            function loadSecondConfiguration() {
                expoints.registerConfig('1646f323-fd3f-425b-927b-422132193c96', { instanceUrl: 'https://customer2.expoints.nl' });
            }
        };
        exp.src = 'https:///<customer#>.expoints.nl/m/Scripts/dist/expoints-external-loader.min.js';
        var s = document.getElementsByTagName('script')[0];
        s.parentNode.insertBefore(exp, s);
    })();
</script>
The callback function is used to register a second configuration using the registerConfig function. 
expoints.registerConfig(configId, options, (optional) callback);
This function also accepts a callback function as the third parameter.

Events

The pop-up provides the following JavaScript events that can be listened to for actions triggered by the customer in the questionnaire:
  1. Question answered
  2. Questionnaire finished
  3. Questionnaire opened
  4. Questionnaire closed

Listening to events

To listen to the above events use the examples given below.

Question answered

Triggered when the customer answers a question. Note that this event is triggered for every given answer (for text answer there is a small debounce). You are responsible for deduplicating the answers. 
document.addEventListener("expoints_answered", function (e) {
    console.log(e.detail);
});
e.detail contains the following data: 
{
    answer: null OR 'text answer',
    baseQuestionId: -1,
    customerId: 123456,
    questionText: 'Example question'
    scales: [] OR [{
        label: 'Answer option 1'
        value: 1,
    },
    {
        label: 'Answer option 2'
        value: 2,
    }]
}

Questionnaire finished

Triggered when the customer finishes the questionnaire. 
document.addEventListener("expoints_questionnaire_finished", function (e) {
    console.log(e.detail);
});
e.detail contains the following data: 
{
    answers: [] OR see example above,
    customerData: [] OR [{
        customerDataColumnId: 1,
        name: 'Name of customer data column 1',
        value: 'Example value 1'
    },
    {
        customerDataColumnId: 2,
        name: 'Name of customer data column 2',
        value: 'Example value 2'
    }],
    customerId: 123456
}

Questionnaire opened

Triggered when a questionnaire is opened. 
document.addEventListener("expoints_questionnaire_opened", function (e) {
    
});

Questionnaire closed

Triggered when a questionnaire is closed. 
document.addEventListener("expoints_questionnaire_closed", function (e) {
    
});

LocalStorage

Below is a detailed list containing all LocalStorage entries used in the pop-up. These are necessary for the working of the pop-up. The pop-up does not use cookies but only LocalStorage.

Name Description Example value
expoints_external_pages_history Array containing all pages visited on the website. Used for target "customer visits website page for second time". ["https://expoints.nl/example1.html","https://expoints.nl/example2.html"]
expoints_external_website_visited Boolean set when leaving website for the first time. Used for trigger "customer returns to website". true
expoints_external_pages_visited_counter Counter containing pages visited by customer. Used for target "customer has visited n website pages". 3
expoints_external_previous_url String containing previous visited URL on website. Used for target "URL"; https://expoints.nl/example1.html
expoints_external_customer_questioned Object containing a date time and boolean whether the customer has been questioned. Used for preventing customer getting multiple questionnaires. {"date":"2021-12-15T13:55:40.995Z","questioned":true}