The Search SDK uses a javascript call to create an Inbenta User Interface (UI) quickly and easily. You can set certain configuration parameters to tune it to your specifications. 

This page describes to set up the Search SDK and introduces available configuration and customization options.

Setup

The Search SDK consists of three different tools:

• A Builder, which builds SDK instances.
• Several Components, which build the UI and print client data.
• A Search Store, that gives you advanced control over components.
• A JS-Client, which interacts seamlessly with Inbenta's Search API.

First, you must include the Search SDK in your website. The Search SDK is available in two versions, with or without polyfills. Polyfills transform newer code methods into methods compatible with IE11 browsers by updating the JS prototype objects. Use a script tag to integrate the Search SDK in a webpage. If you need compatibility with IE11 browsers, use the version with polyfills:

      <script src="https://sdk.inbenta.io/search/<version>/inbenta-search-sdk.js"></script>

If you do not need compatibility with IE11 browsers, you can use the version without polyfills:

      <script src="https://sdk.inbenta.io/search/<version>/inbenta-search-sdk-no-polyfills.js"></script>

Versions

When you set up the SDK for your Inbenta product, you need to specify the version like this:

<script src="https://sdk.inbenta.io/search/<version>/inbenta-search-sdk.js"></script>

Versions are written in MAJOR.MINOR.PATCH format.

Examples

• If only MAJOR is set, this script will use the highest available MINOR version. <script src="https://sdk.inbenta.io/search/1/inbenta-search-sdk.js"></script>
• If MAJOR.MINOR are set, this script will use the highest available PATCH version. <script src="https://sdk.inbenta.io/search/1.19/inbenta-search-sdk.js"></script>
• If you specify the full version, only this exact version will be used. <script src="https://sdk.inbenta.io/search/1.19.1/inbenta-search-sdk.js" integrity="sha384-viZG/3OfKopmj0koWN4ppT4qZ+eAFy5BMTYAIiWcmaDyJDPzVzIW+ajLnV4tfTcl" crossorigin="anonymous"></script>

Starting from version 1.27.0 (2019.05.15), the SDK automatically logs the version in the user info with two keys. sdk_selected_version logs the version specified in your script (which can be MAJOR, MAJOR.MINOR, or full, depending on your preference). sdk_used_version logs the full version that was actually used. This allows the Dashboards to show the version used in a specific session. To configure the Dashboards, contact your Inbenta representative.

Starting the SDK

You need a valid access token to use Inbenta APIs. Follow the steps listed in the Authorization section to set up your page with your token and refresh it automatically.

To create your SDK with a domain key, first obtain the key, then use createFromDomainKey like this:

 var sdk = InbentaSearchSDK.createFromDomainKey(<your_Domain_Key>,<your_API_Key>);

To create our SDK using an access token, first make a server-side call to the /auth endpoint, then use createFromAccessToken like this:

var sdk = InbentaSearchSDK.createFromAccessToken(<your_access_token>,<your_API_Key>);

If you create the SDK with an access token, you must call the server before it expires to receive a new access token. (See the Authorization section.)

If the function returns a promise and the access token cannot be refreshed, it will retry the calls made while the token was valid. For more information, consult Promises support.

Example

In this example, the AJAX call returns the same access token and expiration as the endpoint does. The response is in JSON format:

sdk.setCallbackWhenInvalidAccessToken(function(){
  return new Promise((resolve, reject) => {
    var xhttp = new XMLHttpRequest();
    xhttp.addEventListener( 'load', function() {
      if (this.readyState == 4 && this.status == 200) {
        var object = JSON.parse(this.responseText);
        sdk.client.setAccessToken(object.accessToken, object.expirationAt);
        resolve('success');
      } else {
        reject('error');
      }
    });
    xhttp.open("GET", "?action=getAccesToken", true);
    xhttp.send();
  });
});

Asynchronous integration

This is the recommended integration for the Search SDK. This integration prevents sending extra requests to the API. The idea is that the SDK sends /auth requests to the API automatically when it is set up. You want to prevent these unnecessary requests when the user does not use the Search SDK.

Use cases

Inbenta recommends that you use this integration in the following scenarios:

• The integration uses an existing input in the page to do the searches. This means the SDK does not provide the Searchbox.
• Deflection tools

How should you implement it?

To summarize, you should not load the SDK until you are sure that the user is using the Search functionality. To do this, use the different DOM events: this way, you avoid sending extra /auth requests when users simply access the page without using the functionality.

Example In the following example, you wait until the user puts the focus on the input element before loading the SDK. If the user does not put the focus on the input element, the SDK does not load.

<body>

<div id="app">
    <input id="input" type="text">
    <div class="container">
        <div id="results"></div>
    </div>
</div>
<script src="https://sdk.inbenta.io/search/1.X.X/inbenta-search-sdk.js"></script>
<script>
    var domainkey = '<your_Domain_Key>';
    var apiKey = '<your_API_Key>';
    var sdk;

    document.querySelector("#input").addEventListener('focus', function(e){
        if (!sdk) {
            // Create the SDK instance using your access token and configuration.
            sdk = InbentaSearchSDK.createFromDomainKey(domainkey, apiKey);

            // Components initialization
        }
    });
</script>

</body>

Synchronous integration

This integration is not recommended. Use it only if there is no other option.

Use cases

This integration may apply to the following scenarios:

• The integration uses the SearchBox component, and iprints the results on the page automatically when a user accesses it.
• Integrations where you offer some results upon loading.
• Builder integrations, for cases where you want to display everything when the page loads.

How do you implement it?

This implementation loads the SDK on the page as the page loads. This means that every time a user accesses this page, it sends an /auth request, because it uses the Search SDK.

Example This example below loads the integration with the page, which means that the entire SDK functionality is loaded when the user enters.

<body>
<div id="product-tabs"></div>
<div id="inbentaContainer">
  <div id="inbenta"></div>
</div>
<script type="text/javascript" src="https://sdk.inbenta.io/search/1.X.X/inbenta-search-sdk.js"></script>
<script>

    var domainkey = '<your_Domain_Key>';
    var apiKey = '<your_API_Key>';

  var options = {
   "stats":{
      "text":"Results {{ first }}-{{ last }} of {{ totalResults }} for: {{ query }}"
   },
   "results":{
      "resultsPerPage":5
   },
   "searchBox": {
       "autocompleter":{
        "settingsToShow": ["URL"],
        "showViewAllButton":false
      }
   },
   "refinementLists":{"refinements":[]},
   "refinementTabs":{attributeName: 'XXX'},
   "router": true
};
  // Create the SDK instance using your access token and configuration.
  var sdk = InbentaSearchSDK.createFromDomainKey(domainkey, apiKey);
  var builder = sdk.build('#inbenta',options);
</script>

</body>

Component templates

You can use templates to customize how to render a component with string-based templates or functions.

In text format, templates must be written using mustache. You can only do this for specific parts of the rendered component. Most of the components allow this functionality. Please refer to the specific component documentation and SDK templates for more information.

<div id="app"></div>

<script>
  sdk.build('app', '#app', {
    results: {
      templates: {
        item: '<a href="{{ __url }}" {{{ __clickable }}}>'
          + '{{ title }} ({{ id }})'
          + '</a>'
          + '<p>{{ attributes.PARAGRAPHS }}</p>'
      }
    }
  });
</script>

Tracking

Upon loading, the SDK automatically calls the API to initiate a session, either with the createFromAccessToken function or createFromDomainKey. This is done from the /tracking/session endpoint.

Skin

Main section: Styles

You can change the skin using the skin parameter. There are two skins available and three choices:

• space-cowboy: (default) loads the space-cowboy skin using the space-cowboy.css file.
• ocean-flow: loads the ocean-flow skin using the ocean-flow.css file.
• tatooine-sunset: loads the tatooine-sunset skin using the tatooine-sunset.css file.
• imperial-black: loads the imperial-black skin using the imperial-black.css file.
• teth-sunrise: loads the teth-sunriseskin using the teth-sunrise.css file.
• newtral: loads the newtral skin using the newtral.css file.

You can also load the SDK without a skin. To do so, set the skin parameter to false:

• false: only loads the layout.css file. This loads only layout information, without loading any skin.

If you want to use your own design, Inbenta recommends that you load a skin, then change specific styles using the CSS guide.

config = {
    skin: 'ocean-flow',
}

If you want to build your own CSS from scratch, you can disable the default skin, which will load the layout.css only:

config = {
    skin: false,
}

Then, include your own CSS link:

<link rel="stylesheet" href="https://clientwebsite.com/base.css"></script>

SDK Client

The client can be used either alone or with the normal SDK integration. To access it with the SDK, use the .client parameter:

  sdk.client.<client thing>

For more information, see the js-client section.

External management

See the external management section.

Access token expiration

When using the Domain token, the SDK automatically refreshes the Access token when needed (see the Authorization section). When using the Access token integration, it depends on the configuration parameters autoRefresh and expirationTime. Using these parameters, you can also autorefresh the AccessToken when needed.

If you prefer a custom handling when the Access token expires, you can use the method setCallbackWhenInvalidAccessToken available in the SDK.

Libraries and Browser Support

The JavaScript SDK depends on:

• “@tweenjs/tween.js”: “17.2.0”
• “axios”: “0.26.1”
• “core-js”: “3.22.2”
• “events”: “1.1.1”
• “handlebars”: “4.5.0”
• “has-scrollbar”: “1.0.0”
• “lodash”: “4.17.21”
• “popper.js”: “1.14.4”
• “qs”: “6.11.1”
• “scroll-into-view-if-needed”: “1.5.0”
• “scrollbar-width”: “3.1.1”
• “vue”: “2.5.17”
• “vue-click-outside”: “1.0.7”
• “vue-router”: “3.0.1”
• “vue-sanitize”: “0.2.0”

The following browsers are supported:

• IE 11+ (only in the Search SDK version with polyfills)
• Last version of self-updating browsers:
  • Chrome
  • Firefox
  • Safari
  • Edge

Supported in WebView mobile applications using:

• Android OS 4.4 KitKat or newer
• iOS 8.0+
• macOS 12.2+