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:
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.
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
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
Example of using Share URL with contentFilters parameter:
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:
Contact us to obtain a customer key.
Use this key to AES encrypt your request parameters. Users can generate the key (secure hash) with or without parameters. To include a parameter: include contentFilters as a parameter.
Parameters: contentFilters
Example: contentFilters=[{"fieldName":"opened","values":[1000],"operator":">"}]
Please contact [email protected] for assistance with AES encryption and/or sample code.
Use the Share settings in the dashboard, and click on 'Generate Secure URL' a generate an embeddable URL.
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 *********** -->
<scrip>
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>
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":">"}]_ttl=30
Users can change the default timezone to any of the required timezone. By default, the timezone is set to the dashboard creator's timezone. Here is a list of time zones supported by Knowi. To change the timezone in the secure hash URL, append the _tz parameter at the end of the URL.
_tz=<timezone>
Note:
The _tz parameter can be appended to a post-encrypted URL only.
Make sure to append the _tz parameter after the ? symbol.
Examples:
https://knowi.com/share/secure/giiHglNJBQ0TZHzjG9f8XvpEMvruhisQFQk7V9UisMKllwie/LEr___2nqUZtopDswWtnxfRpTLTCaSdnRknTs3E9YTXwSA90P5VNc4dvm3T8FzDvycPBRvZXvg8X9YYGI1b17hzFqtPnbnlFPD___X+M+TGOJqlyXaD___A8+6aJfVwfNxpeVEWF6yGkingMJcug___lhWfhh1jqa12kN5p0xR___7FF191ic=?_tz=UTC
https://knowi.com/share/secure/giiHglNJBQ0TZHzjG9f8XvpEMvruhisQFQk7V9UisMKllwie/LEr___2nqUZtopDswWtnxfRpTLTCaSdnRknTs3E9YTXwSA90P5VNc4dvm3T8FzDvycPBRvZXvg8X9YYGI1b17hzFqtPnbnlFPD___X+M+TGOJqlyXaD___A8+6aJfVwfNxpeVEWF6yGkingMJcug___lhWfhh1jqa12kN5p0xR___7FF191ic=?_tz=America/New_York
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.
Step 1: On the left hand side menu, click User Settings --> Account Settings tab.
Step 2: 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 are not using it.
Note: Contact [email protected] 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.
User Token: Create an SSO user within your account using your Knowi SSO Customer Token
curl -i -X POST -d "[email protected]&ssoCustomerToken=<SSO_TOKEN>" https://www.knowi.com/sso/user/create
Note: 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.
Session Token: Create a new session token using the returned token from step 1
curl -i -X POST -d "[email protected]&userToken=<USER_TOKEN>" https://knowi.com/sso/session/create
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:
POST https://www.knowi.com/sso/user/create
Parameter | Type | Description |
---|---|---|
ssoCustomerToken | string | Required. Customer-specific SSO Token to authorize SSO user management. |
user | string | Required. email/username of the new or existing user. |
userGroups[] | array of strings | An array of groups the user will be associated with.. Note: Group will be created if it does not exist. Send an empty array ([]) to remove dissociate the user from all groups. |
role | string | Role and permissions to assign the user. Defaults to system user if blank. |
refresh | bool | Boolean. If True, the user's properties (i.e. userGroups[], contentFilter, role) will be updated with new values. |
contentFilter | object | A JSON object to apply a row-level filter on data user is allowed to see. Ex: [{"fieldName": "region", "values":["Canada","Mexico"], "operator":"="}] |
Returns: -
A user specific token. Store this for your user within your system.
Example
curl -i -X POST -d "userGroups[]=First Group&userGroups[]=Second Group&[email protected]&ssoCustomerToken=9ebdlklfWlYuQXPXanqHxq7ZflklfZ1pGC8Ny8l2is9uNhMie" https://www.knowi.com/sso/user/create
Returns a user token back.
POST https://www.knowi.com/sso/session/create
Parameter | Type | Description |
---|---|---|
user | string | Required. email/username of the existing user. |
userToken | string | Required. Token returned from user creation (/sso/user/create) |
Returns: -
A session Id/token
Example
curl -i -X POST -d "[email protected]&userToken=NUAslkrtRTTFMvscpiislikfyfhsgu491is7plqRvwvJGEgm7JVU8ie" https://www.knowi.com/sso/session/create
Returns a session token.
Note: For added security, Both User creation and session creation also has optional domain matching, where we serve requests from specific hosts.
POST: https://www.knowi.com/sso/user/remove
Parameter | Type | Description |
---|---|---|
user | string | Required. email/username of the existing user. |
userToken | string | Required. token returned from user creation (/sso/user/create) |
ssoCustomerToken | string | Required. customer-specific SSO Token to authorize SSO user management. |
To update user level filters, use the following end point:
POST: https://www.knowi.com/sso/user/contentfilters/update
Parameter | Type | Description |
---|---|---|
contentFilter | string | Required. a JSON object to apply a row-level filter on data user is allowed to see. Ex: [{"fieldName": "region", "values":["Italy"], "operator":"="}] |
user | string | Required. email/username of the existing user. |
ssoCustomerToken | string | Required. customer-specific SSO Token to authorize SSO user management. |
Example
curl -i -X POST -d "[email protected]&ssoCustomerToken=9ebdlklfWlYuQXPXanqHxq7ZflklfZ1pGC8Ny8l2is9uNhMie&contentFilter=[{\"fieldName\":\"customer\",\"values\":[\"Costco\"],\"operator\":\"=\"}]" https://www.knowi.com/sso/user/contentfilters/update
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://knowi-web.s3.amazonaws.com/css/custom1.css', 'https://knowi-web.s3.amazonaws.com/css/custom2.css']
},
},
function() { alert("Loaded") }
);
Create User with user level filters enabled:
curl -i -X POST -d "userGroups[]=Default&[email protected]&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.
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
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"
The Search Based Analytics API lets you
1. Develop applications to list query suggestions and retrieve the associated response from the query.
2. 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 "[email protected]&ssoCustomerToken=" 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 "[email protected]&userToken=" https://knowi.com/sso/session/create
3. Embed: Write a Javascript file with the session token returned from step 2
Knowi.render('#knowi-div', {
type: 'nlp',
token: "ii7Cdf7QJy3PaYQLrdZLaGgMnq3Dy2Q1JEhiiuDR9GG64ie",
url: 'http://localhost:9090',
view: {
nlpOptions: {
icon: "off",
css: {
background: 'transparent',
width: '80%'
},
placeholder: "Try: total sales for canada this week",
help: "off",
helpText: "Ability to customize the help text of the question mark",
defaultView: "visual"
}
}
}, function () { });
Note: For embedding Search Analytics, type must be nlp
Note: The defaultView can either be data or visual. By default, it is set to data. If set to visual, then a visualization tab will show up in NLP results of the embedded view.
Following API's may 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
The easiest method for embedding a Knowi display (dashboard or visualization) is with the copy-paste embed code. Navigate to a dashboard or visualization on Knowi and copy the Embed Code from the Share option.
Once acquired, this code can be pasted into HTML. This method is useful for simple embeddings, such as embedding into websites, blogs, or internal knowledge bases, but only very simple embedding scenarios should use the embed code.
Note: The JavaScript API is recommended for more control of the look and feel. It is not significantly more work to embed with the JavaScript API and doing so will gain you flexibility and power in your embedded deployment.
Embedding with an iFrame
The basic embed code using the iFrame looks something like this:
HTML:
The secure embed code using the iFrame looks something like this:
iFrame Resources
The JavaScript API is an alternative approach to the iFrame embed method. Use the Knowi JavaScript API to integrate Knowi visualizations into your own web applications. The Javascript API provides better functionality to match the intended look and feel for your end-users.
Some of the things that you can do with the JavaScript API:
See a JSFiddle demo of the Javascript API.
<script src="https://www.knowi.com/minify/knowi-api.min.js"></script>
div
element in the page body
where you want to insert the Knowi visualization:
<div id="knowi-div"></div>
function loadChart() {
Knowi.render('#knowi-div', {
type: 'share',
dashboard: 'BYhXXCeu0Ego8zA1FqtLOOM4BDWot5AYBLI7PWrQTbsie',
url: "https://www.knowi.com/",
view: {
title: true,
header: true
}
}, function () {
});
}
Note: The complete Javascript API Reference to customize your embed is here.
loadChart();
The full code sample from the above example can be found here.
To use the JavaScript API object specified below, be sure to specify the URL to the JavaScript API file in your web page. For more information, see Embedding with Javascript API or code samples. The JavaScript API file is a library that contains functions for interacting with the JavaScript API. It's a minified file and production-ready to be downloaded by the browser.
This section defines the available options for configuring the Knowi
Javascript Class.
Name | Type | Descriptions |
---|---|---|
type | string | type of asset/view to embed Supported values: share for dashboard, secure for secure hash dashboard, shareWidget for widget, shareWidgetSecure for secure hash widget, single for single sign-on, nlp for natural language query |
dashboard | string | share URL of dashboard/widget |
dashboardId | integer | ID of dashboard/widget |
hash | string | Encrypted hash from secure share dashboard/widget. Must be used with type: secure, shareWidgetSecure |
token | string | session token from Single Sign-On. Needed with type: single |
renderType | string | specifies how embed will be rendered. Options are object, iframe. Defaults to iframe |
url | string | url for on-premise deployments. Defaults to www.knowi.com |
view | Object | customizable options for the embedded display. |
This section defines the available options for configuring the view object from the Knowi class.
Name | Type | Descriptions |
---|---|---|
title | bool | enable widget title and action menus |
filter | bool | enable dashboard/widget filter |
autoHeight | bool | automatically adjust dashboard height to div |
border | bool | enable borders around the widget |
widgetSpacing | bool | spacing between widgets (px). Possible values between 0-200 |
setting | bool | enable widget settings |
resize | bool | enable widget on a dashboard to be resized |
drag | bool | enable widget on a dashboard to be rearranged |
scroll | bool | enable scroll on a dashboard |
header | bool | enable dashboard header including dashboard name and settings |
dashListIcon | bool | enable/disable the dashboard listing dropdown (defaults to true) Note: Only applicable for 'single' type of embed. (since the others have it off by default). |
backgroundColor | string | background-color of dashboard Supported formats: rebeccapurple, HEX value: #92a8d1, RGB: rgb(201, 76, 76), RGBA: rgba(201, 76, 76, 0.6) |
analytics | bool | enable Ad-hoc Analytics mode for widgets. Applicable with types: shareWidget, shareWidgetSecure |
chat | bool | enable customer support chat |
menu | bool | enable side menu bar with system actions as needed |
menuOptions | Object | disable side navigation menu. Defaults to showing all menu options. Applicable with type: single Available options: Read more about menu options below.
|
css | array | inject custom CSS files to override the default styling. Example: ['https://knowi-web.s3.amazonaws.com/css/custom1.css', '...'] |
contentFilters | array | JSON array of user content filters. Applicable with types: share, shareWidget Example: [{"fieldName": "department", "values": ["sales", 19], "operator": "="}, {...}] |
nlpOptions | Object | customizable settings for NLP search bar. Applicable with type: nlp
|
dashFiltersBar | bool | enable dashboard filters top bar |
dashFiltersIconToSidePanel | bool | enable filter icon in top filters bar clickable, which open up the right side dashboard filters panel |
The menu options available are:
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://knowi-web.s3.amazonaws.com/css/custom1.css', 'https://knowi-web.s3.amazonaws.com/css/custom2.css']
},
}, function() {
alert("Loaded")
});
See sample JSFiddle.
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.
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'.
Include the Javascript API:
<script src="//www.knowi.com/minify/knowi-api.min.js"></script>
To render Knowi widget on a page, add the following javascript:
Knowi.render('#myDiv', {
type: 'shareWidget',
widget: 'nZcdj3DThlSDuZhrh6E8KVP9TLZFStoWWAOCGh8zP0cie'
}, function () {
alert("Loaded");
});
The content filters also can be passed to widget same as for dashboards.
Knowi allows you to embed the Presentation mode for a specific dashboard. This includes embedding with SSO, share URL, iframe, Knowi JS library, i.e. all kinds of embedding. To embed the presenter, you need to enable the "presenterOptions" field in the View Object Reference.
Here is an example:
function loadChart() {
Knowi.render('#knowi-div', {
type: 'secure',
hash: "rcf9rdm6zTDd6KIz9EblkO0e0BfEFF0SCjH9RABg=",
dashboard: "4kjl45kipgqULyXaT5fAUD3ipIypbipPNq2wm6D197pJKCnQnTx",
view: {
title: true,
border: true,
header: true,
backgroundColor: "lightblue",
setting: true,
presenterOptions: {
instantSights: true,
hideCloseIcon: true,
loop: true,
excludeGrids: true,
autoAdvance: 10
}
}
}, function () {
});
}
This Presenter object includes more options such as:
Name | Descriptions | :
---|---|
instantSights | includes plain English insights from the widget |
hideCloseIcon | hides the X button in the Presenter, so user will not be able to return to dashboard |
loop | loops through the slides from the beginning once finished |
excludeGrids | excludes grid widgets |
autoAdvance | auto rotate slides, in seconds. If not set, then it will be user-driven |
Scaling an embedded analytics deployment of Knowi often means providing content to different groups of users. There is a security implication of making sure the different groups do not see each others' data (and metadata). There is also a deployment and maintenance consideration: Common dashboards should have to be built only once, even if the different groups of users access different data with those common dashboards.
With Knowi Embedded, there are three main fundamental approaches to maintaining separation between tenants.
A single tenant architecture provides a dedicated Knowi server for each tenant. This deployment architecture is suitable when there may be restrictions that mandate that data of different tenants can't be located on the same physical machine.
Row-level security is both a security and content management concern. The simplest way to make sure users only see their data is to manually build a dashboard for each of them. This is not scalable, so Knowi provides a variety of ways to build a single dashboard that is filtered to the correct data. The correct method to use depends on your data environment.
Here is some guidance (details for each of the methods are below):