Integration¶

Integrating BOON is as simple as adding our Javascript (JS) tag to your site, and an HTML element wherever you want the interface displayed.

Javascript¶

The BOON JS tag provides an easy route for integration into websites, acting as a local agent to the BOON API and abstracting away the control logic.

The JS tag provides the following features out of the box:

Rendering of the profile builder in a specified location
Updating of questions and options to enable a dynamic profile builder experience
Saving of user responses to the profile builder in real time
Generation and rendering of item recommendations on finishing the profile builder
Generation and rendering of live replacement recommendations for each user
Automated collection of user feedback data to continuously improve results
Generation of analytics events allowing tracking of BOON interactions from existing analytics solutions

Importing the tag¶

The BOON JS tag should added to the <head> of each page where interactions are required. This includes any pages where:

The BOON user interface should be rendered
User feedback data should be collected

The following lines of JS should be added to import the tag:

(function(c, s) {
    var t = document.createElement('script');
    t.async = true;
    t.src = 'https://cdn.boon.so/' + c + '/' + s + '/loader.js';
    document.head.appendChild(t);
})('<clientId>', '<serviceId>');

The tag takes two arguments, which provide its configuration:

clientId - Unique identifier provided for each client
serviceId - Unique identifier provided for each service

Tag Configuration¶

The boonConfig object is set globally in the window, and contains per-page configuration of how BOON operates. Default values are set for all keys, but by specifying them before the tag is defined, these can be overridden on a per-page basis.

Note

The boonConfig variable only takes effect when the main BOON JS is loaded. Changes made after this will have no effect.

Warning

When setting values in the boonConfig object, take care not to override any values that may already be set. If the boonConfig object is already present on the page, the object keys should be added or updated directly. Overwriting the object may clear important configuration and break the integration.

The following configuration values can be set:

Name	Description
questionFlow	Name of the question flow to display
displayMode	Manually specifies the way in which the user interface is rendered. One of `inline`, `modal` or `none`.

For example, to show the ice-cream question flow, the following config would be used:

window.boonConfig = {questionFlow: 'ice-cream'};
(function(c, s) {
    var t = document.createElement('script');
    t.async = true;
    t.src = 'https://cdn.boon.so/' + c + '/' + s + '/loader.js';
    document.head.appendChild(t);
})('example-client', 'example-service');

HTML¶

Once the JS tag is added to the page, the BOON interface can be displayed in one of two ways; either inline on the page or in a modal triggered by a user’s click.

Inline¶

Simply include a <div> element to the location on the page where you want the interface to be rendered, with the id parameter set to boon-container. This should look like the following:

<div id="boon-container"></div>

The BOON JS tag will then automatically render the user interface into this container. It looks best if the container stretches across the entire screen/browser width.

Note

For optimal performance when rendering inline, set the displayMode configuration varaible to inline as described in the Display Mode section below. This enables additional loading optimisations and does not require waiting for the page to fully load before initialising the BOON UI.

Display Mode¶

The displayMode configuration variable manually overrides the display method for the user interface. Usually this is dynamically detected according to the elements on the page as described above, however in certain circumstances it may be useful to manually control this. This is especially useful when page rendering performance is critical, as the inline value allows the JS to initialise before the page has fully loaded, which would otherwise not be possible when dynamically detecting elements.

A value of none disables rendering of the BOON interface altogether (the same behaviour as if no container or trigger elements are defined).

A value of inline forces the interface to be rendered inline. If no container element is present on the page, nothing will be rendered. Modal display is explicitly disabled, so even if a modal trigger element is present on the page (and no container element is present), the modal will not be rendered. The inline value enables loading optimisations to minimise the time to render the BOON interface.

A value of modal forces the interface to be rendered in a modal. If no modal trigger elements are present on the page, nothing will be rendered. Inline display is explicitly disabled, so even if a container element is present on the page the inline interface will not be rendered. The modal value also enables loading optimisations to minimise the time to render the BOON interface, however these have a lower priority than the inline optimisations as it is assumed that modal rendering is not critical for the page to function.