SDK Setup

Important: Make sure that you have all your credentials and necessary assets available before you start.

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.

Note: All examples shown are set in a Production environment.

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:

      <script src="https://sdk.inbenta.io/search/<version>/inbenta-search-sdk.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.

Important:

  • Do NOT cache or store these files, otherwise you will not benefit from bug fixing and minor upgrades.
  • Inbenta strongly recommends that you use a MAJOR.MINOR.PATCH version.

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>

Note: An SRI check is available for this SDK. For more information, see the SDK Subresource Integrity page. Remember that SRI only works with full versions.

Starting the SDK

Note: For a complete description of keys and authorization methods, see the Authorization section.

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 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_Domain_Key>,<your_API_Key>);

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

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

Note: Each situation is different and it depends a lot on the kind of page you want to create.

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 string format, templates must be written using mustache. You can only do this for specific parts of the rendered component.

<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. The SDK also tracks the user's IP address with the /tracking/session/user endpoint.

Styles

If you want to use custom CSS styles, include your own CSS link:

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

For more information about available customization options, see the CSS guide.

Important: The SDK modifies the HTML class to add browserDetection to ensure that the styles are correctly displayed in different browsers.

Configuration options

The following table shows available InbentaSearchSDK parameters:

Name Type Default Description
userType integer 0 Defines the profiles identifier from the Search App's knowledge base. It uses an x-inbenta-user-type header to make API requests. For more information about this header, see the API Routes.
environment string production Defines the source environment from Search App's knowledge base. It uses an x-inbenta-env header. For more information about this header, see the API Routes.
labels object Override the default texts used in components. Each component has its own default labels that can be overriden. For more information, see the components section. See the list of all SDK labels for their customization or translation.
skin string space-cowboy Defines the components appearance (skin). For more information, see the CSS Guide.

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>

Note: You have to start the SDK before using the client.

For more information, see the js-client section.

External management

See the external management section.

Access token expiration

You can change the token expiration message (see the Authorization section) by rewriting the function calling this message:

sdk.setCallbackWhenInvalidAccessToken(callback: Function);

If you create the SDK using accessToken, you need a function that calls the server to update it before it expires and get a new access token. The following AJAX call should return the same access token and expiration our endpoint does.

In this example assume the AJAX call return a text with a JSON.

var refreshAccessToken = function(){
  var xhttp = new XMLHttpRequest();
  xhttp.onreadystatechange = function() {
    if (this.readyState == 4 && this.status == 200) {
      var object = JSON.parse(this.responseText);
      sdk.client.setAccessToken(object.accessToken, object.expirationAt);
    }
  };
  xhttp.open("GET", "getAccessToken", true);
  xhttp.send();
};
sdk.setCallbackWhenInvalidAccessToken(function(){
 refreshAccessToken();
});

SDK Change Log

See the change log section.

Libraries and Browser Support

The JavaScript SDK depends on:

  • "@tweenjs/tween.js": "^17.2.0",
  • "axios": "^0.17.0",
  • "es6-promise": "^4.2.4",
  • "es6-shim": "^0.35.3",
  • "events": "^1.1.1",
  • "has-scrollbar": "^1.0.0",
  • "js-cookie": "^2.2.0",
  • "lodash": "^4.17.5",
  • "popper.js": "^1.14.1",
  • "qs": "^6.5.1",
  • "scroll-into-view-if-needed": "^1.5.0",
  • "scrollbar-width": "^3.1.1",
  • "vue": "^2.5.16",
  • "vue-click-outside": "^1.0.7",
  • "vue-router": "^3.0.1",
  • "vue-sanitize": "^0.1.0"

The following browsers are supported:

  • IE 11+
  • Last version of self-updating browsers:
    • Chrome
    • Firefox
    • Safari
    • Edge