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>

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.

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_access_token>,<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 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.

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. Most of the components allow this functionality. Please refer to the specific component documentation 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.

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.

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

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

Supported in WebView mobile applications using:

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