asdfasdfsadf

Embeddable Analytics

We provide multiple embed options:

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:

  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 your Account Manager if you need assistance with AES encryption.

  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}

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

  1. Create a user in Knowi and associate to groups via an API. Store the returned token for this user.
  2. Create a session token using the token for the user.
  3. Access the dashboards using the session token.

API details

  1. User Creation:

    POST https://api.cloud9charts.com/sso/user/create
    

    Parameters:

    user: name of the user in your system to create a Single Sign-On for.

    userGroups[]: Array of User groups in text form. User groups are groups that the user subscribes to.

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

    contentFilter: Optional. A JSON string to force filter dashboards with given parameters for the user. See example section for further details.

    role: Optional. Determines the level of functionality available to this user. admin: Enables full admin rights, including creating and managing new users. user: Default. No User management rights, but can create their own datasources and queries, as well as access to the dashboards and widgets (as well as creating their own). viewer: View-only rights to the dashboards they are allowed to see.

    Returns:

    A user specific token. Store this for your user within your system.

  2. Create a Session for a user:

    POST https://api.cloud9charts.com/sso/session/create
    

    Parameters:

    user: name of the user in your system

    userToken: Token for this user generated during the user creation process

    Returns:

    A session Id/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://api.cloud9charts.com/sso/user/remove
    

    Parameters:

    user: name of the user to remove.

    userToken: Stored token associated to the user.

Example

Example using curl:

Create User:

curl  -i -X POST -d "userGroups[]=First Group&userGroups[]=Second Group&user=a@a.com&ssoCustomerToken=9ebdlklfWlYuQXPXanqHxq7ZflklfZ1pGC8Ny8l2is9uNhMie" https://api.cloud9charts.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://api.cloud9charts.com/sso/session/create
Returns a session token.

iFrame URL, with the session token:

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

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://api.cloud9charts.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://api.cloud9charts.com/sso/user/contentfilters/update

Parameters:

user: name of the user to remove.

userToken: Stored token associated to the user.

Example:

    curl  -i -X POST -d "user=demoSSO@knowi.com&userToken=7Yx2UAnr2aq6AK66vML2YnisDuZm1BkdNGsBntYO38BUie&contentFilter=[{\"fieldName\":\"customer\",\"values\":[\"Costco\"],\"operator\":\"=\"}]" https://api.cloud9charts.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://api.cloud9charts.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

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="//knowi.com/minify/cloud9charts-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 or widget. Supported values: 'share', 'secure', 'single', 'shareWidget' and 'shareWidgetSecure'
dashboard ID 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
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
token Authorization token for single signon API requests. Used only for 'single' type
view Display properties. Full list of the properties and default values:

title: false

filter: false

autoHeight: false (auto adjusts the height of the dashboard to the div)

border: false

setting: false

resize: false

menu: false

actions: false (determines whether the filter and reset icons are displayed)

drag: false

header: false

scroll: true

css: none (array of urls)

url: none (url to hit for on-premise deployments)

backgroundColor: none (transparent, white, blue, fff, cacaca)

contentFilters: none (array of filters, only applicable for share & single types)

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="//knowi.com/minify/cloud9charts-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.