Don't lose your mojo
Contact us to convert your trial account!
Embeddable Analytics
We provide multiple embed options:
- Simple URL based embedding.
- Secure URL Embed with encrypted request payload.
- Single SignOn API that enables token exchange from users in your system to map to Knowi with user rights & permissions.
Dashboards and widgets can be embedded using using our Javascript API, or using an iFrame.
URL Embed
Simple URL Share and Embed
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:
Contact us to obtain a customer key.
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.
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 *********** -->
<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
Single Sign-On is an alternative to the above URL based schemes, when you want to fine grained control over users, groups and access rights associated to both.
Flow
- Create a user in Knowi and associate to groups via an API. Store the returned token for this user.
- Create a session token using the token for the user.
- Access the dashboards using the session token.
API details
User Creation:
POST https://www.knowi.com/sso/user/createParameter 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 existsrole 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.
Create a Session for a user:
POST https://www.knowi.com/sso/session/createParameter 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.
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>
To delete a Single Sign-On User:
POST: https://www.knowi.com/sso/user/removeParameter 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 contentExample: 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 contentExample: curl -i -X GET https://www.knowi.com/sso/user/logout?token="9sBRdisBevkFvfIbb3HnipqjutS00JIjWpTcGKUPe2wMAie"
NLP API
The NLP API lets you develop applications to list query suggestions and retrieve the associated response from the query. With this API, you can make NLP requests to search across datasets within a given user's account.
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.
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).
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, logout: false}. disable side menu buttons. Defaults to show all. Supported options: logo, dashboards, widgets, datasources, queries, ml, settings, help, logout.
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.
You can override these properties, for example:
|
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
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.