OnSite > OnSite Javascript SDK
Menu
OnSite Javascript SDK
For most websites, you will not need to use our Javascript SDK – our implementation team will handle all aspects of implementing your OnSite units. This page will describe when and how to use the OnSite Javascript SDK
Before You Start The OnSite SDK requires per-client configuration. The documentation below is for example only. Your Customer Success Representative will deliver customized documentation detailing available units and filters, as well as example use cases specific to your implementation.
The OnSite SDK allows for dynamic components to employ OnSite recommendations. Good use cases include hover-activated menus, filter-able content areas, and infinite-load content areas.
Unit markup
Markup for units is managed by OnSite. For each request, OnSite will build the markup using a template which has been defined during the implementation phase. It is recommended that the client manage the CSS for the unit.
Ensure that the async property on the OnSite script inclusion is set to true.
In the document head, set a global variable _onSiteQ
as shown below, then use _onSiteQ.push(fn)
to add functions to the queue for execution when the Onsite script has been loaded, or immediately execute if the script is already loaded.
Include the _OnSiteQ above the OneSpot script
HTML
<head>
<script>
var _onSiteQ = _onSiteQ || [];
</script>
<!-- OneSpot script should be included BELOW the _OnSiteQ -->
</head>
Note: Push is the only method available for the class _onSiteQ. Once the OnSite script has loaded, normal array methods will not be available for the global _onSiteQ.
Methods cannot be executed directly Methods should be executed within a function. The function containing the method execution is passed to the
_onSiteQ
via the push
method. See examples. method | params |
---|---|
window.onespot.onsite.getRecommendations | options: Unit Options. |
window.onespot.onsite.moreRecommendations | options: Unit Options. |
Object.
property | value |
---|---|
units | Array of unit |
onRender | Function. The onRender function will receive a response object with an errors array of error objects where the keys are the units with errors. This response can be used to determine the success or failure of the request. The absence of an error for a requested unit indicated a successful rendering. |
onResponse | Function. The onResponse function will receive a response object where each property in the object is the name of a requested unit. The value of that property is an object with one property, hasMorePages , where the value is a boolean describing whether or not more recommendations are available for the requested options. |
Example onRender error response object
{
"errors": [
{
"unit-name": "Selector #null-selector did not match any element"
}
]
}
Example onResponse object
{
"unit-name": {
"hasMorePages": true
}
}
unit
Object.
Object.
property | value |
---|---|
name | String. A list of the names of available units will be provided during implementation. |
filter | String. Filters are collections of rules that determine what can be recommended. Currently, only one filter can be requested per unit per request. A list of available filters will be provided during implementation. |
selector | String. The DOM node to which OnSite will inject the unit. When using the window.onespot.onsite.getRecommendations function, the unit will replace any content in the DOM node for the selector. When using the window.onespot.onsite.moreRecommendations function, each request via this function will append to the DOM node for the selector. |
Example options
var options = {
units:[{
name: 'unit-name',
filter: 'filter_name',
selector: '[data-content="displayer-name"]'
},{
name: 'another-unit',
filter: 'filter_name',
selector: '#selector-id'
}],
onRender: function(response){console.log(response);},
onResponse: function(response){console.log(response);}
}
To make a request for units, pass a function to the
_onSiteQ
via the push
method. Functions should define options and execute of the the available methods.One or more units may be loaded by calling our
getRecommendations
function, passing in options, within your function. getRecommendations
function myFunc() {
var options = {
units:[{
name: 'displayer-name',
filter: 'filter_name', //optional, will default to "default" filter
selector: '[data-content="displayer-name"]'
},{
name: 'another-displayer',
filter: 'filter_name',
selector: '[data-content="another-displayer"]'
}],
onRender: function(res){ console.log(res); }
}
window.onespot.onsite.getRecommendations(options);
}
_onSiteQ.push(myFunc);
JavaScript
function myFunc() {
var options = {
units:[{
name: 'unit-name',
filter: 'filter_name',
selector: '[data-content="displayer-name"]'
},{
name: 'another-unit',
filter: 'filter_name',
selector: '#id-name'
}],
onRender: function(response){console.log(response);},
onResponse: function(response){console.log(response);}
};
window.onespot.onsite.getRecommendations(options);
}
_onSiteQ.push(myFunc);
The
onResponse
response object from the initial load will indicate whether or not more pages are available for the requested options. To make additional requests, use the moreRecommendations
method and pass the same options for the unit as the initial request. JavaScript
function myMoreFunc() {
var options = {
units:[{
name: 'unit-name',
filter: 'filter_name',
selector: '[data-content="displayer-name"]'
},
onRender: function(response){console.log(response);},
onResponse: function(response){console.log(response);}
};
window.onespot.onsite.moreRecommendations(options);
}
_onSiteQ.push(myMoreFunc);