Developers

SDK Configuration

Knowledge SDK configuration options

The following sections describe all the configuration parameters that are available for the Knowledge SDK, their default values and available options. You can set the configuration in the main config parameter of the SDK build method.

Config is an optional parameter.

Important information

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

accessTokenExpiration

The accessTokenExpiration parameter determines the expiration time of the access token for the Knowledge API. Use the value returned by the auth endpoint.

config = {
  accessTokenExpiration: 'access token returned by the auth endpoint',
};

connectionEntryPoint

The connectionEntryPoint parameter defines the Inbenta API endpoint where the SDK performs the Auth connection. You can select any available endpoint from the ones defined in Regions and Endpoints.

Default value: https://api.inbenta.io/

config = {
  connectionEntryPoint: 'https://api.inbenta.io/',
};

preRequestAction

The preRequestAction parameter allows you to define a global function for the SDK configuration. This function returns a promise before making any requests to the API. If the returned promise is rejected, the request cannot be made, which means you can use this parameter for example to make sure that the user is still logged in before continuing with the API request.

config = {
  preRequestAction: personalizedFunction,
};

userType

The userType parameter defines which contents and/or content versions will be displayed, depending on the user types defined in the Settings > User Types screen of the Knowledge instance. Define user types using the numeric ID from the Settings > User Types screen. API requests will include it in the x-inbenta-user-type header. For more information about this header, see the API Routes page. You can, for example, find it in the GET /contents/ids endpoint.

The default value is 0, meaning that the SDK will display all contents and content versions destined for the Default user type.

Example:

config = {
  userType: '0',
};

Environment

The environment parameter defines the working environment of the Knowledge SDK, meaning the source environment of the module's Knowledge Base. Options are:

  • production (default): This environment logs the data for the reports displayed in Inbenta Dashboard screens when the Production environment setting is selected in the Knowledge instance. It also retrieves contents and categories published to Production.
  • preproduction: This environment logs the data for reports displayed in Inbenta Dashboard screens when the Preproduction environment setting is selected in the Knowledge instance. It also retrieves the contents and categories published to Production.
  • development: This environment logs the data for the reports displayed in Inbenta Dashboard screens when the Development environment setting is selected in the Knowledge instance. It also retrieves the contents and categories published to Test.

For an overview of what each environment represents in terms of the Knowledge SDK environment, the Dashboards environment and the Knowledge Base Version, please consult the table below:

Knowledge SDK environment Dashboards environment Knowledge Base Version Purpose
Production Production Production To consult data from real user interactions
Preproduction Preproduction Production To use for internal tests using the Production Knowledge Base, separating the resulting logs from the ones reflecting real user interactions
Development Development Test To use for preliminary tests using the Test Knowledge Base

API requests include this parameter value in the x-inbenta-env header. For more information about this header, see the API Routes page.

Example:

config = {
    environment: 'preproduction'
};

Labels

Each component has its own default labels, but those can be modified. Use the labels parameter to override the default texts used in components. Please see a list of all the default labels below:

config = {
  labels: {
        'POPULAR_TITLE' : 'Popular',
        'POPULAR_TEXT' : 'Frequently answered questions',
        'PUSHPOPULAR_TITLE' : 'Maybe you are interested in:',
        'PUSHPOPULAR_TEXT' : 'Interesting contents',
        'RESULTS_TITLE' : 'Results',
        'RESULTS_TEXT' : 'Search results for',
        'RESULTS_NOT_FOUND_TITLE' : 'No results found',
        'RESULTS_NOT_FOUND_TEXT' : "We're sorry, but we couldn't find any answer for your query.",
        'RESULTS_BACK_BUTTON' : 'Back',
        'PUSH_TITLE' : 'Push',
        'PUSH_TEXT' : 'Maybe you are interested',
        'CATEGORIES_TITLE' : 'Categories',
        'CATEGORIES_SIDEBAR_TITLE' : 'Categories',
        'CATEGORIES_BREADCRUMB_BACK_BUTTON' : 'Back',
        'CATEGORIES_BACK_BUTTON' : 'Back',
        'CATEGORIES_BREADCRUMB_HOME': 'Home',
        'TITLE_CONTENT_LIST' : 'Contents',
        'SEARCH_BOX_BUTTON' : 'Send',
        'SEARCH_BOX_PLACEHOLDER' : 'Question',
        'RELATED_INTRODUCTION':'Related contents',
        'RATINGS_INTRODUCTION' : 'Was this answer helpful?',
        'RATINGS_COMMENT_INTRODUCTION' : 'Why this content is not correct?',
        'RATINGS_COMMENT_PLACEHOLDER' : '',
        'RATINGS_SUBMIT_COMMENT_BUTTON' : 'Send',
        'RATINGS_GRETTINGS_TEXT' : 'Thanks for your comment!',
        'REFRESH_INVALID_ACCESS_TOKEN' : 'Something went wrong. Please, refresh the page',
        'REFRESH_TITLE' : 'Oooops...!',
        'REFRESH_BUTTON' : 'Refresh',
        'INSTANTS_TITLE': 'Instants Faqs',
        'LAST_CHANCE_TITLE': 'Last Chance',
        'LAST_CHANCE_CANCEL': 'Cancel',
        'LAST_CHANCE_SUBMIT': 'Submit',
        'RELATED_UQ': 'Related user questions',
        'USER_QUESTIONS': 'User questions',
        'SHOWING_CONTENTS_UQ': 'Contents related to',
        'CATEGORIES_DROPDOWN_TITLE': 'Categories',
        'CATEGORIES_DROPDOWN_PLACEHOLDER': 'Choose category',
        'DIFFERENT_LANGUAGE_DETECTED': 'It seems you are asking a question in a language we did not expect. Please look for the language you need in the menu.'
      }
}

To change the text of a label, send an object with the new label. This function updates only the defined labels, and keeps the others unchanged.

Example:

config = {
    labels: {
          'ratings_introduction': 'New introduction to prompt end users to rate the content'
      }
}

For a full overview of the default labels per component and what they look like in the SDK, click here.

Skin

Main section: Styles

The skin parameter defines the SDK components' appearance with through predefined CSS files or “skins”. Its default value is space-cowboy.

The available skins are:

  • space-cowboy: Loads the space-cowboy skin using the space-cowboy.css file.
  • ocean-flow: Loads the ocean-flow skin using the ocean-flow.css file.
  • tatooine-sunset: Loads the tatooine-sunset skin using the tatooine-sunset.css file.
  • imperial-black: Loads the imperial-black skin using the imperial-black.css file.
  • teth-sunrise: Loads the teth-sunrise skin using the teth-sunrise.css file.

You can also load the SDK without a skin. To do so, set the skin parameter to none:

  • none: Loads only the layout.css file. This loads only layout information, without loading any skin.

If you want to use your own design, Inbenta recommends that you load a skin, then change specific styles using the CSS guide.

Example:

config = {
    skin: 'ocean-flow',
}

LogIp

The logIp parameter determines whether logs the end users' IP addresses are logged in the “User Information” column of the Dashboard > Sessions > Details screen of the Knowledge instance. The default value is false.

Example:

config = {
    logIp: 'true',
}

Result in the Dashboard > Sessions > Details screen:

LogUserAgent

The logUserAgent parameter defines whether the end users' identifiers are logged in the “User Information” column of the Dashboard > Sessions > Details screen. You can configure how you want to display this information using the setUserInfo method.

The default value is false.

Example:

config = {
    logUserAgent: 'true',
}

Result in the Dashboard > Sessions > Details screen:

Source

The source parameter defines the name of the source that will appear as a filter option in the Filters sidebar of the Dashboard screens in the Knowledge instance, for example ‘web browser' or ‘mobile app'. of the API calls. API requests will include this value in the x-inbenta-source header. For more information about this header, see the API Routes page. You can find it in the POST /Search endpoint, for example.

The default value is null.

Example:

config = {
    source: 'mobile app',
}

Result in the Filters sidebar of the Dashboard screens in the Knowledge instance:

The searchBox parameter offers the autofocus option to determine whether the cursor is automatically set in the search bar when the Knowledge search page loads, so end users can start typing immediately without first needing to move their cursor to the search bar. The default value is false.

Example:

config = {
        "searchBox": {
            "autofocus": 'true'
        }
    },

Result in the search screen:

Results

The results parameter offers multiple options to configure how search results are displayed to the end user at the level of:

results:

  • showBackButton: Determines whether the SDK displays a “Back” button under the list of search results, so the end user can easily return to the search screen. Default value: true

contents:

  • showRelated: Determines whether the SDK displays a result's related contents when the end user clicks the result. Default value: true

ratings:

  • elements: A series of elements that help you configure how end users should be presented with the option to rate contents and search results
    • id: The ID of the rating element defined in the Settings > Ratings screen of the Knowledge instance
    • label: The text to be displayed for the element, for example “yes” or “no” if the rating introduction is “Was this answer helpful to you?”
    • comment: Whether or not end users should be able to leave a comment with their rating
    • final_message: The message displayed to the user after they rate the content

Default configuration/example:

config = {
         "results": {
              "showBackButton": true,
              "contents": {
                  "showRelated": true
        },
              ratings: {
                  elements:[
                      {
                          id:1,
                          label: 'Yes',
                          comment: false,
                          final_message: 'Thanks for your comment!',
                      },
                      {
                          id:2,
                          label: 'No',
                          comment: true,
                          comment_message: 'Why this content is not correct?',
                          final_message: 'Thanks for your comment!'
                      }
                ]
          }
    },

Result in the Knowledge SDK:

When an end user answers “yes”, they cannot leave a comment and receive the final message after rating the content:

When an end user replies “no”, they are asked to leave a comment before they receive the final message:

The popular parameter offers the following options to configure how popular contents are displayed:

  • length: Determines the maximum number of popular contents that can be displayed. Default value: 5
  • interval: Determines the period taken into account to determine which are the popular contents based on the number of user clicks. Possible values are:
    • lastDay: Only the clicks of the past day are taken into account to determine which are the most popular contents. (Default)
    • lastMonth: Only the clicks of the past month are taken into account to determine which are the most popular contents.
    • allTime: All clicks are taken into account to determine which are the most popular contents.

Example:

config = {
       "popular": {
            "length": 5,
            "interval": "lastDay"
        }
},

Result on the Knowledge search page:

Push

The push parameter offers the option to configure the maximum number of push contents that can be displayed. Default value: 5

Example:

config = {
       "push": {
            "length": 1,
        }
},

Result on the Knowledge search page:

Categories

The categories parameter offers the option to configure the maximum number of contents that can be displayed per category. Default value: 100

Example:

config = {
       "categories": {
            "length": 100,
        }
},

SanitizeOptions

For security reasons, Inbenta escapes several HTML tags using the sanitizeOptions parameter. It contains a default whitelist of HTML tags, which you can modify.

The default whitelist is specified 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', 'u', 'strong', 'em', 'strike', 'code', 'hr', 'br', 'div',
    'table', 'thead', 'caption', 'tbody', 'tr', 'th', 'td', 'pre', 'img', 's', 'figure', 'span', 'mark'],
  allowedAttributes: {
    a: ['href', 'name', 'target'],
    img: ['src', 'alt'],
    '*': ['style', 'class'],
    td: ["colspan", "rowspan"],
    ol: ["start"]
  },
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 is the list of URL schemes that are allowed (for example in href or src attributes).

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 an 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', 'u', 'strong', 'em', 'strike', 'code', 'hr', 'br', 'div',
    'table', 'thead', 'caption', 'tbody', 'tr', 'th', 'td', 'pre', 'img', 's', 'figure', 'span', 'mark', 'iframe'],
    allowedAttributes: {
      a: ['href', 'name', 'target'],
      iframe: ['src'],
      img: ['src', 'alt'],
      '*': ['style', 'class'],
      td: ["colspan", "rowspan"],
      ol: ["start"]
    },
    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.

Interceptors

See the Interceptors section.