SDK Setup

Important

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

Note

All examples shown are set in a Production environment.

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:
<script src="https://sdk.inbenta.io/km/1.20.0/inbenta-km-sdk.js" integrity="sha384-5SAzy0v2YMX1NHcUSm3+DoU5NpVHAuop/bdHHWImdX43YPlr15S0z8cNCiEGu5LC" 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.

Important

• For best security and performance, Inbenta recommends that you store these files on your own server.

• If you decide to use Inbenta-hosted SDK files, Inbenta **strongly recommends** that you use a MAJOR.MINOR.PATCH version, as well as SDK Subresource Integrity for additional security for your website.

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.

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 = InbentaKmSDK.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 = InbentaKmSDK.createFromDomainKey(<your_Domain_Key>,<your_API_Key>);

Customizing the refresh token notification labels

Name Default Description
REFRESH_TITLE Oooops...! Notification title
REFRESH_INVALID_ACCESS_TOKEN Something went wrong. Please, refresh the page Notification body
REFRESH_BUTTON Refresh: Notification button

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: Here, 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>
Caution

Since contents and categories are presented automatically, the page requests are made to the API upon loading even if the users do no click or search anything. This can have an important impact on the API rate limits, especially if there is a high traffic on the page. In case you want to add the search functionality in all your pages (for instance in the header) it is recommended to avoid using components that load contents automatically.

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

Widget Launcher Widget Opened

Caution

If you want to use this code "as is" in production environments, you must copy and use them from your servers. To avoid any potential issues, do not use the direct Inbenta links for Production, as Inbenta may change or update links or files without prior notice.

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.

Caution

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

Libraries and Browser Support

The JavaScript SDK depends on:

  • vue 2.4.2
  • axios 0.16.2
  • CORS

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+