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.

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

Configuration options

Config is an optional parameter.

Caution: Changes to the configuration can affect all the Inbenta components and templates. If you want to add a component with a different configuration, you must create another SDK instance in the same page.

Use the config parameter when you create the session:

var sdk = InbentaKmSDK.createFromAccessToken(access_token:String, inbenta_key:String, config:Object);
Name Type Default Description
accessTokenExpiration string 0 Expiration time returned by the auth endpoint
environment String production Defines source environment from the App's knowledge base. It will be used in client as 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.
logIp boolean false Log the user's IP in user info.
logUserAgent boolean false Log the user's user agent in user info.
sanitizeOptions Object *Sanitize Default Defines the allowed tags and the allowed attributes for per tag.
skin String default Defines the components' appearance with CSS files. Its default value is 'default'.
source string null Defines source of the API calls. Used in client as a x-inbenta-source header. For more information about this header, see the API Routes.
userType integer 0 Defines the profile identifier from the KM App's Knowledge Base. It will be used in client as x-inbenta-user-type header to make API requests. For more information about this header, see the API Routes.

Sanitizer

For security reasons, Inbenta escapes several HTML tags. A whitelist of these HTML tags exists, which you can modify.

The default whitelist is below. If you do not specify sanitizeOptions in the build configuration, the default value applies:

    allowedTags: ['h1','h2','h3', 'h4', 'h5', 'h6', 'blockquote', 'p', 'a', 'ul', 'ol',
        'nl', 'li', 'b', 'i', 'strong', 'em', 'strike', 'code', 'hr', 'br', 'div',
        'table', 'thead', 'caption', 'tbody', 'tr', 'th', 'td', 'pre','img'],
    allowedAttributes: {
        a: [ 'href', 'name', 'target' ],
        img: [ 'src' ],
        div: ['id']
    },
    allowedSchemes: [ 'http', 'https', 'ftp', 'mailto' ]

AllowedTags is the list of HTML tags that you can use. AllowedAttributes lists the attributes that you can use in the allowed HTML tags (for example, href in an a tag, or src in an image). HTML classes are blocked by default, but you can add them to the whitelist with the following statement: allowedClasses. AllowedSchemes URL schemes in cases where href, src, etc.

Caution : Any change you make to the default whitelist is strictly at your own risk. Inbenta does not recommend the addition of additional tag and will not accept any responsibility or liability for any issue caused by changes in the default whitelist.

The following example includes a additional iframes HTML tag and a test class in the p HTML tag and the scheme data:

config={
  sanitizeOptions : {
    allowedTags: ['h1','h2','h3', 'h4', 'h5', 'h6', 'blockquote', 'p', 'a', 'ul', 'ol',
      'nl', 'li', 'b', 'i', 'strong', 'em', 'strike', 'code', 'hr', 'br', 'div',
      'table', 'thead', 'caption', 'tbody', 'tr', 'th', 'td', 'pre','img','iframe'],
    allowedAttributes: {
      a: [ 'href', 'name', 'target' ],
      iframe:['src'],
      img: [ 'src' ]
    },
    allowedClasses: {
      'p': [ 'test']
    },
    allowedSchemes: [ 'http', 'https', 'ftp', 'mailto', 'data' ]
  }
}

SDK Methods

Name Description
untilReady() (deprecated) Since version 1.21.0 it returns a resolved promise. Before it waits until a valid accessToken and valid sessionToken is generated.

Use JS-Client on SDK

See the JS-Client on sdk section.

Cross selling

See the cross selling management section.

External management

See the external management section.

Interceptors

See the Interceptors section.

Open specific content

See the open specific content management section.

Speech to text

See the speech to text management section.

Change log

See the change log section.

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+