OnSite Javascript SDK

OnSite > 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.

How It Works

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.

Including the script for async function queuing

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

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.

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);}
}

Making Requests

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.

Example - Initial Load

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);

Example - Load More

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);