Embeddable Analytics

Knowi makes it easier to create and embed analytics and visualizations into other business applications including your own and into cloud applications like Shopify or Salesforce.

Multiple options are available for embedding:

  • Public Embedding 
  • Token based embedding
  • Authenticated Embedding through Single Single On

Embedding offers the ability to customize the user experience of dashboard interaction and functionality of the embedded applications. We provide multiple embed options:

Dashboards and widgets can be embedded using using our Javascript API, or using an iFrame.

Getting Started

Knowi's embedded solution allows you to add the power of interactive visualization to external websites and applications. Knowi offers built-in features to distribute live dashboards with a customizable, tailored experience using a Javascript API and the security of Single Sign-On.

Embedding can be a single dashboard or visualization to the full application with integration to handle authentication, personalization, and content management.

Key concepts

Javascript API: API for embedding and programmatically managing the interaction and experience. Ideal for integrating with the functionality of the embedding application

Secure Hash: For public embedding, URL parameters such as user filters can be encrypted.

Authenticated Access: Method to guarantee security and governance for embedded views through Single Sign-On. If users of your application sign in, they will be allowed a passthrough to access Knowi content using the same credentials. Removes the friction of prompting a Knowi login screen.

User Filtering: Ability to securely filter a dashboard's data based on the Knowi login information. This is ideal in multi-tenant scenarios if you have a single dataset or database for multiple users or groups of users. Applying a user filter provides the functionality of utilizing the same content and style across users whilst ensuring each user can see only the rows governed by their user filter

URL Embed

Simple URL Share and Embed

Use this option if you'd like to share or embed a dashboard for public access without security. To generate a public URL for a dashboard, click on 'Generate Shareable URL' from the 'Share' tab of the dashboard.

Note: This makes the dashboard publicly accessible, without requiring a login. Do not use this option for sensitive data.

In addition, the embed code can also be used to embed the dashboard into your own portal/HTML pages.

To turn off a unique public URL, click on 'Disable Share URL'.

To add filter parameters to the share URL, pass in contentFilters parameter to the URL, where the value is in encoded JSON form.

Example: URL Parameter example: contentFilters=[{"fieldName":"opened","values":[1000],"operator":">"}]

Full URL, with the parameter and encoded JSON:
https://www.knowi.com/d/3cKltxiizxNFgxjRvanZwY2WZoiikPo5ip3EqS13cii1KdQie?contentFilters=%5B%7B%22fieldName%22%3A%22opened%22%2C%22values%22%3A%5B1000%5D%2C%22operator%22%3A%22%3E%22%7D%5D

Secure URL Embed

Use this option to securely embed dashboards where you can filter the data based on parameters that are encrypted (using your customer key). This ensures that the request is not tampered with.

Steps:

  1. Contact us to obtain a customer key.

  2. Use the key to AES encrypt your request parameters. Include contentFilters as a parameter (mandatory).

    Parameters: contentFilters

    Example: contentFilters=[{"fieldName":"opened","values":[1000],"operator":">"}]

    Please contact support@knowi.com for assistance with AES encryption and/or sample code.

  3. Use the Share settings in the dashboard, and click on 'Generate Secure URL' a generate an embeddable URL.

  4. Build the URL with the generated hash at in step 2 at runtime. Embed into an iFrame inside your portal (or use the JavaScript API) Example: https://www.knowi.com/share/secure/VyqOBEBfyKt7ZUzLyH68Vm3lT34NisUIYM1VOis0IpI38ie/{secureHash}

Example Javascript Usage:

<HEAD>

 <script src="https://www.knowi.com/minify/knowi-api.min.js"></script>

 <!-- *********** Edit here *********** -->

 <script>

 function loadChart() {
     Knowi.render('#knowi-div', {
       type: 'secure',
       hash: "rcf9rdm6zTDd6KIz9EblkO0e0BfEFF0SCjH9RABg=",
       dashboard: "4kjl45kipgqULyXaT5fAUD3ipIypbipPNq2wm6D197pJKCnQnTx",
       view: {
         title: true,
         border: true,
         header: true,
         backgroundColor: "lightblue",
         setting: true
       }
    }, function () {
       });
 }

 </script>

</HEAD>

<BODY onload="loadChart()">

<div id="knowi-div"></div>

</BODY>
</HTML>

Link Expiry

You can also specify a time to expire for a given request, so that the link with the same parameters cannot be reused. To add an expiry, pass in the following two parameters to the request prior to the encryption routine:

Current Epoch Time: _t
Expiry in seconds: _ttl (default is 60 seconds if _t is present without _ttl).

Example url before passing it through the hashing/encryption routine: contentFilters=[{"fieldName":"opened","values":[1000],"operator":">"}]&t=1537661183&ttl=30_

Single Sign-On API

In some scenarios, you want to guarantee the authentication of users before viewing Knowi content. Single sign-on enables the users signed into your application to view a protected-private Knowi resource without the need of signing in once again on Knowi. Afterward, a new browser session and cookie will be issued to the browser.

User identity, permissions, access level, and attributes are all constructed within the browser session of the single sign-on user, which is created using a unique customer token. Anyone with access to the customer token may create an SSO user to which that Knowi instance is connected to, as any user, with any permission. See our example code to learn how to generate an SSO flow.

Generating Knowi Customer Token:

In order to create and manage SSO users, you'll first need a Knowi SSO Customer Token. 

On the left hand side menu, click User Settings --> Account Settings tab.  From the Customer Settings section, select ?Generate? in the SSO Token field .

Protect the Knowi SSO Token as you would any credentials to your Knowi instance and keep SSO Token section disabled if you?re not using it.

Note: Contact support@knowi.com if the SSO TOKEN option is not available in your Knowi Customer Settings.

Getting Started: Embedding with SSO requires some code writing to seamlessly integrate into your web application. You can find several example scripts on our SSO examples GitHub repository. 

The following simplifies the information needed to embed with SSO.

  1. User Token: Create an SSO user within your account using your Knowi SSO Customer Token

    curl -i -X POST -d "user=email@domain.com&ssoCustomerToken=<SSO_TOKEN>" https://www.knowi.com/sso/user/create
    

Additional parameters can passed when generating a creating an SSO user token, such as assignment to groups, roles/permission, user filters. See the API reference for usage.

  1. Session Token: Create a new session token using the returned token from step 1

    curl -i -X POST -d "user=email@domain.com&userToken=<USER_TOKEN>" https://knowi.com/sso/session/create
    
  2. Embed: Write a Javascript section with the session token returned from step 2

      function loadKnowiUser() {
        Knowi.render('#knowi-div', {
          type: "single",
          token: "BYhXXCeu0Ego8zA1FqtLOOM4BDWot5AYBLI7PWrQTbsie",
          url: "https://www.knowi.com/",
          view: {
            title: true,
            header: true
          }
        }, function () {
        });
      } 
    

Note: Alternatively, you can log in directly on a browser or iFrame the URL using the session token returned from step 2

      https://www.knowi.com/sso/user/login?token=<SESSION_TOKEN>

SSO API Resources:

  • SSO code samples created and maintained by Knowi | link 
  • Embedding SSO with Javascript API | link

API details

  1. User Creation:

    POST https://www.knowi.com/sso/user/create
    
    Parameter Required? Description
    ssoCustomerToken yes customer specific token to authorize SSO user creation
    user yes email of the new user or existing user
    userGroups[] no Array of User groups in text form that users will subscribes to.
    Note: Group will be created if it does not exists
    role no role with permissions the user should have. Defaults to user role if blank.
    refresh no Boolean. If True user properties (i.e. userGroups[], contentFilter, role) will be refreshed and updated with new values
    contentFilter no JSON. User's content filters

Returns: - A user specific token. Store this for your user within your system.

  1. Create a Session for a user:

    POST https://www.knowi.com/sso/session/create
    
    Parameter Required? Description
    user yes email of the newly created user or existing user
    userToken yes user token returned during user creation process

Returns: - A session Id/token

Example

Create User:

curl  -i -X POST -d "userGroups[]=First Group&userGroups[]=Second Group&user=a@a.com&ssoCustomerToken=9ebdlklfWlYuQXPXanqHxq7ZflklfZ1pGC8Ny8l2is9uNhMie" https://www.knowi.com/sso/user/create
Returns a user token back.

Create Session, using the token for the user:

curl  -i -X POST -d "user=a@a.com&userToken=NUAslkrtRTTFMvscpiislikfyfhsgu491is7plqRvwvJGEgm7JVU8ie" https://www.knowi.com/sso/session/create
Returns a session token.

For added security, Both User creation and session creation also has optional domain matching, where we serve requests from specific hosts.

  1. Access the dashboards : Use the JavaScript API or iFrame the url in the following format: https://www.knowi.com/sso/user/login?token=<session token>

  2. To delete a Single Sign-On User:

    POST:  https://www.knowi.com/sso/user/remove
    
    Parameter Required? Description
    user yes email of user to remove from account
    userToken yes stored user token associated to user
    ssoCustomerToken yes A customer specific token to authorize user deletion

SSO Embedding 

Option 1: iFrame the URL, with the session token:

https://www.knowi.com/sso/user/login?token=b7E5pofgis9nBjSyPxUclksflkfltS1ZEPhhHhG2MBZis34QJiiBFn8ie

Option 2: Use the JavaScript API: 

Knowi.render('#knowi-div', {
    type: 'single',
    token: '...',
    view: {
      title: true,
      css: ['https://rawgit.com/AntonLapshin/csharp/master/custom1.css', 'https://rawgit.com/AntonLapshin/csharp/master/custom2.css']
    },
   },
   function() { alert("Loaded") }
);

User level filters and roles

Create User with user level filters enabled:

curl  -i -X POST -d "userGroups[]=Default&user=a17@a.com&ssoCustomerToken=9ebdlklfWlYuQXPXanqHxq7ZflklfZ1pGC8Ny8l2is9uNhMie&contentFilter=[{\"fieldName\":\"customer\",\"values\":[\"LinkedIn\"],\"operator\":\"=\"}]" https://www.knowi.com/sso/user/create

Then create the session token and iFrame the URL with the session token like in the example above.

More on User level filters here.

Updating User Filters

To update user level filters, use the following end point:

POST:  https://www.knowi.com/sso/user/contentfilters/update

Parameters:

user: name of the user to remove.

ssoCustomerToken: A customer specific token to authorize user creation. Please contact us to obtain your customer specific token.

Example:

    curl  -i -X POST -d "user=demoSSO@knowi.com&ssoCustomerToken=9ebdlklfWlYuQXPXanqHxq7ZflklfZ1pGC8Ny8l2is9uNhMie&contentFilter=[{\"fieldName\":\"customer\",\"values\":[\"Costco\"],\"operator\":\"=\"}]" https://www.knowi.com/sso/user/contentfilters/update

Listing API

The following end points can be used to retrieve groups, dashboards, queries and widgets:

GET /sso/dashboards

Parameters: token. SSO session token. Required.

Returns: Returns a list of dashboards and details for each dashboard in JSON Array form

Example: curl -i -X GET https://www.knowi.com/sso/dashboards?token="9sBRdisBevkFvfIbb3HnipqjutS00JIjWpTcGKUPe2wMAie"

GET /sso/widgets:

Parameters: token. SSO session token. Required.

Returns: Returns a list of widgets and details for each widget in JSON Array form

GET /sso/queries:

Parameters: token. SSO session token. Required.

Returns: Returns a list of queries associated to the user

GET /sso/groups:

Parameters: token. SSO session token. Required.

Returns: Returns a JSON list of user groups associated to the user

User Activity

Get last timestamp of a users activity

GET /sso/session/lastActive

Parameters: token. SSO session token. Required.

Returns: timestamp in milliseconds for an SSO user's last system activity. Returns "-1" if user is inactive.

Example: curl -i -X GET https://www.knowi.com/sso/session/lastActive?token="9sBRdisBevkFvfIbb3HnipqjutS00JIjWpTcGKUPe2wMAie"

Extends the lifetime of SSO session token by 30 minutes

PUT /sso/session/keepAlive

Parameters: token. SSO session token. Required.

Returns: Returns No content

Example: curl -i -X PUT https://www.knowi.com/sso/session/keepAlive?token="9sBRdisBevkFvfIbb3HnipqjutS00JIjWpTcGKUPe2wMAie"

Logout and terminate an SSO user session

 GET /sso/user/logout

Parameters: token. SSO session token. Required.

Returns: Returns No content

Example: curl -i -X GET https://www.knowi.com/sso/user/logout?token="9sBRdisBevkFvfIbb3HnipqjutS00JIjWpTcGKUPe2wMAie"

Search Based Analytics API

The Search Based Analytics API lets you + Develop applications to list query suggestions and retrieve the associated response from the query. + Embed a Google Search like interface to enable plain english requests to search across datasets within a given user's account.

Using Knowi's Search Analytics empowers your end-users the ability to ask questions of their data in English. Think of this as a Google search on your datasets. This functionality can be embedded in your application through Single Sign-On. Try it out.

Similar to embedding with SSO and the Javascript API, the steps to embedding Search Analytics is almost identical and can be achieved in three steps:

1. User Token: Create a Knowi user token for a new or existing user

curl -i -X POST -d "user=email@domain.com&ssoCustomerToken=<SSO_TOKEN>" https://knowi.com/sso/user/create

2. Session Token: Create a Knowi session token with the user token from step 1

curl -i -X POST -d "user=email@domain.com&userToken=<USER_TOKEN>" https://knowi.com/sso/session/create

3. Embed: Write a Javascript file with the session token returned from step 2

function loadSearchAnalytics() {
    Knowi.render('#knowi-div', {
        type: 'nlp',
        token: "BYhXXCeu0Ego8zA1FqtLOOM4BDWot5AYBLI7PWrQTbsie",
        url: 'https://www.knowi.com',
        view: {
            nlpOptions: {
                icon: "off",
                css: {
                    background: 'transparent'
                },
                placeholder: "Try: total sales for canada this week",
            }
        }
    }, function () {
    });
}

Note: For embedding Search Analytics, type must be nlp

Following API's mmy be used to create your own search bar. Here are the relevant API calls:

GET: /sso/nlp/suggestions

Parameter Required? Description
token yes SSO session token
query yes Query to process

Returns: - A list of suggestions as json array

POST: /sso/nlp/parse


Parameter Required? Description
token yes SSO session token
query yes Query to process
datasetId yes Dataset ID that your query should point to
format no Format of the response (json, txt). Defaults to json

Returns: - Data as json or txt array

JavaScript Embed API

The JavaScript API is an alternative approach to the iFrame embed method.

See a JSFiddle demo of the Javascript API.

Installation

Include the Javascript API:

<script src="//www.knowi.com/minify/knowi-api.min.js"></script>

Usage

To render Knowi dashboard on a page, add the following javascript:

<script>
    Knowi.render('#myDiv', {
      type: 'share',
      dashboard: 'CnzzWr6ZGrii4BYsa295HoVWzNB7VaZey6StgO1uFw2kie'
    }, function () {
        alert("Loaded");
    });
</script>

Options

Option Comments
type Type of access to dashboard, widget or widget analytics mode. Supported values: 'share', 'secure', 'single', 'shareWidget', 'shareWidgetSecure' and 'nlp'
dashboard URL of the dashboard or widget. This can be obtained from the Share URL textbox from the dashboard/widget share window. Applicable for 'share', 'secure', 'shareWidget' and 'shareWidgetSecure' types
dashboardId ID of the dashboard or widget. Alternative to the URL method. This can only used in tandem with single sign on, after the user has been authenticated separately.
hash Hash of the 'secure' shared dashboard or widget. Only applicable for 'secure' and 'shareWidgetSecure' types. This is the AES encrypted hash based on your key
renderType specifies how embed will be rendered. Options are: object, iframe. Defaults to iframe
token Authorization token for single signon API requests. Used only for 'single' type
url Url of backend to hit for on-premise deployments.
view Display properties. Full list of the properties and default values:

title: false. Visibility of title of each widget. Title include widget name and widget control buttons.

filter: false. Visibility of filter button for widgets and/or dashboard. For dashboard only applicable if header is visible (header: true).

autoHeight: false. Auto adjusts the height of the dashboard to the div.

border: false. Visibility of border of widgets.

widgetSpacing: spacing between widgets (px). Possible values between 0-200

setting: false. Visibility of widget settings menu button.

resize: false. If true then widgets allowed to be resized by user with mouse.

menu: false. Visibility of side menu with system actions. Only applicable when type is 'single'.

drag: false. If true then allows to drag widgets on the dashboard with mouse.

header: false. Visibility of dashboard header (including title and filter button).

dashListIcon: true. enable/disable the dashboard listing dropdown. Only applicable for 'single' type of embed.

scroll: true. Determines whether the dashboard is scrollable. If set to false the content may be truncated if not fit into view.

analytics: false. Applicable to shareWidget and shareWidgetSecure: if set 'true' then widget will be expanded to analytics mode.

chat: true. Visbility of customer support chat icon.

css: none. Array of urls. See more about css bellow bellow in next sections.

menuOptions: {logo: false, profile: false}. disable side menu buttons. Defaults to show all. Supported options: logo, dashboards, widgets, queries, alerts, reports, more, help, profile, ml, agent, opsdash.

backgroundColor: none. Background color of dashboard. Values: Transparent, white, blue, fff, cacaca.

contentFilters: none Array of filters, only applicable for 'share' and 'shareWidget' types. See more about filters bellow in next sections.

nlpOptions: customizable settings for NLP search bar. Applicable with type: _nlp_

           
            nlpOptions: {
              icon: "off",
              css: {
                  background: 'transparent',
                  width: '100%'
              },
              placeholder: "Try: total sales for canada this week",
              help: "select * ",
              helpText: "help me"
            }
             


You can override these properties, for example:


          view: {
            title: true,
            resize: true,
            backgroundColor: 'transparent',
            scroll: false
          }
          

CSS Customization

You own custom CSS can be injected into the API. Simply specify a comma separated list of CSS files and their full path during the initialization.

Knowi.render('#cloud9charts', {
    type: 'touchdown',
    username: 'name',
    password: 'pass',
    view: {
      title: true,
      css: ['https://rawgit.com/AntonLapshin/csharp/master/custom1.css', 'https://rawgit.com/AntonLapshin/csharp/master/custom2.css']
    },
}, function() {
    alert("Loaded")
});

See sample JSFiddle.

Filters

To pass in filters:

    Knowi.render('#cloud9charts', {
       type: 'share',
       dashboard: 'CnzzWr6ZGrii4BYsa295HoVWzNB7VaZey6StgO1uFw2kie'
       view: {
         title: true,
         contentFilters: [
            {
               "fieldName":
               "opened",
               "values":[1000],
               "operator":">"
            },
            {
                "fieldName":"message_type",
                "values":["marketing"],
                "operator":"="
            }
         ]
       },
    }, function() {
       alert("Loaded")
    });

Note: Secure URL modes requires contentFilters to be encrypted.

Samples

  1. Simple HTML file with JavaScript embed example: Download
  2. Rotating dashboards sample: Download

Widget Level Embedding

In addition to dashboard level embed options outlined above, you can also share a widget by itself. To generate a shareable URL for a widget, click on 'Generate Shareable URL' from the 'Share' tab of the widget options dropdown.

Note: This makes the widget publicly accessible, without requiring a login. Do not use this option for sensitive data.

To turn off a unique public URL, click on 'Disable Share URL'.

### Embed a widget via the Javascript API

Include the Javascript API:

<script src="//www.knowi.com/minify/knowi-api.min.js"></script>

### Usage

To render Knowi widget on a page, add the following javascript:

  <script>
      Knowi.render('#myDiv', {
        type: 'shareWidget',
        dashboard: 'nZcdj3DThlSDuZhrh6E8KVP9TLZFStoWWAOCGh8zP0cie'
      }, function () {
          alert("Loaded");
      });
  </script>

The content filters also can be passed to widget same as for dashboards.