OnSite > OnSite Javascript SDK

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

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.

HTML
<head>
  <script>
    var _onSiteQ = _onSiteQ || [];
  </script>
  <!-- OneSpot script should be included BELOW the _OnSiteQ -->
</head>
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.
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);