The Knowledge Manager 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 Knowledge Manager SDK and introduces available configuration and customization options.

Setup

The Knowledge Manager SDK consists of three different tools:

• A Builder, which builds SDK instances.
• Several Components, which print client data.
• A JS-Client, which interacts seamlessly with Inbenta's API.

First, you must include the Knowledge Manager SDK in your website.The Knowledge 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 Knowledge SDK in a webpage. If you need compatibility with IE11 browsers, use the version with polyfills:

<script src="https://sdk.inbenta.io/km/1.20.0/inbenta-km-sdk.js" integrity="sha384-5SAzy0v2YMX1NHcUSm3+DoU5NpVHAuop/bdHHWImdX43YPlr15S0z8cNCiEGu5LC" crossorigin="anonymous"></script>

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

<script src="https://sdk.inbenta.io/km/{version}/inbenta-km-sdk-no-polyfills.js" integrity="{hash-type}-{hash}" crossorigin="anonymous"></script>

Versions

(See the Change log for reference.)

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

<script src="https://sdk.inbenta.io/km/<version>/inbenta-km-sdk.js" integrity="<hash-type>-<hash>" crossorigin="anonymous"></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/km/1/inbenta-km-sdk.js"></script>
• If MAJOR.MINOR are set, this script will use the highest available PATCH version.
  <script src="https://sdk.inbenta.io/km/1.2/inbenta-km-sdk.js"></script>
• If you specify the full version, only this exact version will be used.
  <script src="https://sdk.inbenta.io/km/1.2.3/inbenta-km-sdk.js" integrity="sha384-wHpdEnBmhUfPw2ahBg61E9Ck9riu5b1RnAXQVt+UlTQKyh0jt7kJioQPysaFVtPG" crossorigin="anonymous"></script>

Starting from version 1.26.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 = InbentaKmSDK.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 = InbentaKmSDK.createFromAccessToken(<your_access_token>,<your_API_Key>);

Customizing the refresh token notification labels

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 if it is resolved after you refresh the access token, it will retry the calls made while the token was refreshing. 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();
  });
});

Implementation Use Cases

KM SDK can be implemented in numerous ways. Depending on the use case an implementation may be efficient or not. These are a few common use cases and the best way to implement them to reduce the impact on the API rate limits.

Support Main Page

A common use case is to create the main support page with multiple elements to help users find what they are looking for such as a search box, a list of popular contents, a list of pushed contents and categories.

Builder

The build method creates all these components efficiently within the div element defined as a parameter. It is the easiest and quickest way to implement the KM SDK.

<body>
    <div id="inbenta">
    </div>
    <script type="text/javascript">
        /* CREDENTIALS */
        var domainKey = '<your_domain_key>';
        var inbentaKey = '<your_API_key>';
        var sdk = InbentaKmSDK.createFromDomainKey(domainKey, inbentaKey, {});
        sdk.build('#inbenta');
    </script>
</body>

You can adapt it using the options parameter, however it does not accept much customisation so you may need to create the components you want individually.

<body>
    <div id="inbenta">
        <div id="searchbox"></div>
        <div id="autocompleter"></div>
        <div id="results"></div>
        <div id="popular"></div>
        <div id="push"></div>
        <div id="categories"></div>
    </div>
    <script type="text/javascript">
        /* CREDENTIALS */
        var domainKey = '<your_domain_key>';
        var inbentaKey = '<your_API_key>';
        /* SDK Initialization */
        var sdk = InbentaKmSDK.createFromDomainKey(domainKey, inbentaKey, {});
        /* Display Search Box */
        var searchBox = sdk.component('searchBox', '#searchbox', {});
        /* Add autocompleter */
        var autocompleter = sdk.component('autocompleter', '#autocompleter', {});
        autocompleter.linkToSearchBox(searchBox);
        /* Add results */
        var results = sdk.component('results', '#results', {});
        results.linkToSearchBox(searchBox);
        /* Add popular */
        sdk.component('popular', '#popular', {});
        /* Add push */
        sdk.component('push', '#push', {});
        /* Add categories */
        sdk.component('categories', '#categories', {});
    </script>
</body>

<body>
    <header>
        <div id="searchbox"></div>
        <div id="autocompleter"></div>
    </header>
    <div id="inbenta">
        <div id="results"></div>
    </div>
    <script type="text/javascript">
        /* CREDENTIALS */
        var domainKey = '<your_domain_key>';
        var inbentaKey = '<your_API_key>';
        /* SDK Initialization */
        var sdk = InbentaKmSDK.createFromDomainKey(domainKey, inbentaKey, {});
        /* Display Search Box */
        var searchBox = sdk.component('searchBox', '#searchbox', {});
        /* Add autocompleter */
        var autocompleter = sdk.component('autocompleter', '#autocompleter', {});
        autocompleter.linkToSearchBox(searchBox);
        /* Add results */
        var results = sdk.component('results', '#results', {});
        results.linkToSearchBox(searchBox);
    </script>
</body>

Floating Widget

You can implement a support section that is available in all the pages of your website as a floating widget. The widget is located in a corner of the page. When a user has a doubt, they can click on the widget to view a pop-up with the help elements you want to show.

Here is a code example to do this: https://github.com/inbenta-integrations/km_sdk_widget. Follow the instructions in the README to set it up in your environment.

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. Depending on the parameters passed in the configuration, it may also tracks the user's browser and IP address with the /tracking/session/user endpoint.

The session is maintained as long as the user remains active in the page, which means they send at least one request every 30 minutes. Otherwise, another session is started with the same sessionToken.

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.

Libraries and Browser Support

The JavaScript SDK depends on:

• vue 2.5.17
• axios 0.26.1
• CORS

The following browsers are supported:

• IE 11+ (only in the Knowledge 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+