Embedded analytics made easy with Cumul.io integration.

Browse through SaaS communities on Twitter, LinkedIn, Reddit, Discard, name it and you’ll see that a common theme appears in many of them. This theme can go by many names: BI, Analytics, Insights and so on. It’s natural, we do business, we collect data, we succeed or fail. We want to review them all, evaluate some of the data we have, and take action. This need has led to the development of many projects and tools that make life easier for anyone who wants to view data. But, when humans have it, humans want more. And in the world of BI and analytics, “more” often comes in the form of embedding, branding, custom styling and accessibility. Which means more work for developers and more time on account. So, naturally there has been a need for BI tools that will let you do all this.

Let’s make a list of the challenges you may face as a builder and maintainer of these dashboards.

  1. You want to make dashboards available to end users or viewers from within your own application or platform.
  2. You want to manage different dashboard collections (ie “integration”)
  3. You want to be able to assign user-specific rights to dashboards and sets of datasets.
  4. You want to make sure that users only have access to their data.

Cumul.io Provides a tool we call. Integration Which helps to address these challenges. In this article I will tell you what integration is, and how to setup one. The good news is that the above code requires minimal code and most of it can be set within the Cumul.io UI.

Some background – integration

One Integration Cumul.io has a structure that defines a set of dashboards intended to be used together (as in a single application). This is what we use. Embedded Dashboards in an application In other words, in order to embed dashboards in an application, we give the application access to the integration to which they belong. You can link dashboards to an integration and manage what kind of access rights end users of the integration will have to these dashboards and datasets. The dashboard can be part of more than one integration, but may have different access rights to different integrations. When it comes to embedding, there are many SDKs available to make life easier no matter what your stack looks like. ۔

Once you have a Cumul.io account and if you are the “owner” of an organization in Cumul.io, you will be able to manage and manage all your integrations through the Integration tab. Let’s take a look at an example Cumul.io account. Below you can see the dashboards that a Cumul.io user may have created:

Although these are all dashboards created by this user, it is likely that not all dashboards are for the same end users, or there is no application for this issue. So, the owner of this Cumul.io account will create and maintain an integration (or more!); Let’s take a look at what it looks like to them:

So, it looks like the owner of this Cumul.io account has two separate applications.

Now let’s see what the process of creating an integration and adding its dashboards to an application looks like. The good news is, as mentioned earlier, many of the steps you need to take can be done within the Cumul.io UI.

Disclaimer: For the purposes of this article, I will focus entirely on the integration section. So, I’ll leave everything with the creation and design of the dashboard and we’ll start with a pre-made set of imaginary dashboards.

What we will do:

Integration formation

For simplicity, let’s just make an integration. Let’s say we have an analytics platform that we maintain for our company. There are three dashboards we want to provide to our end users: the Marketing Dashboard, the Sales Dashboard and the Leads Dashboard.

We say that anyone from the dashboard who created or accessed this account would only want to use the following for this specific project.

New integration.

To create an integration, we go to the Integration tab and select New Integration. The dialogue that emerges will already give you an idea of ​​what your next steps will be:

Dashboard selection

Next, you will be able to choose which of your dashboards will be included in this integration. You will also be able to give Integration a name, which I have decided here will be a “very important integration” appropriately:

Once you’ve confirmed your selection, you’ll have the option to define a slug for each dashboard (highly recommended). These can be used later by embedding dashboards in your application. You’ll see later that slugs make it easier to reference dashboards in your frontend code, and also make it easier to change dashboards if needed (as you can see from the dashboard ID in frontend code). I don’t have to worry).

Access rights.

You will then set up integration access rights for the use of the data sets dashboards. Here we set it to “can see”. For more information on access rights and what they include, check out our associated datasets for integration:

Filters and parameters (and multi-tenant access)

Side note: To help multi-tenant access – which will be understood in this imaginary setup – Cumul.io makes it possible to set parameters and filters on the data set that the dashboard uses. This means that every user who logs into your analytics platform sees only the data that they personally access to the dashboards. You can imagine that access to this view will be based on what sector the end user works for in the company. To learn more about how to set up a multi-tenancy with Cumul.io, check out our article, “Multinance with Auth0 on Cumul.io Dashboards”. This can be done within the dashboard design process (which we are skipping), making it easier to imagine what we are filtering. But here, we will configure these filters in the integration creation process.

Here, we set filters that may require datasets. In this scenario, as we filter by consumer segments, we define a. department Parameters and filters based on:

And sound! Once you’ve configured them, you’ve successfully created an integration. The next dialog will give you instructions on what your next steps will be to embed your integration:

You will now see this brand new integration in your Integration tab. This is where you get instant access to the integration ID, which will be used to embed dashboards later.

good news! Once your integration is done, you can always edit it. You can remove or add dashboards, change dashboard slugs, or access rights. So you don’t have to worry about creating new integrations as your application changes and gets ready. And since editing integration is all over the UI, you don’t have to worry about resetting a developer. Non-technical users can customize these integrations on the go.

Embedding dashboards.

Let’s see where we want to go. We want to provide custom dashboards within the app. Simple, the user logs into an app, the app has dashboards, they view the dashboards with the data they are allowed. This might look like an example:

Someone had a very specific idea of ​​how they wanted to provide the dashboard to the end user. They wanted a sidebar where they could flip through each dashboard. It could be something different. What we will focus on is how we can embed these dashboards in our application regardless of what the host request is.

Cumul.io comes with a set of publicly available SDKs. Here I show you what you would do if you used Node SD. Check our developer documentation to see if other SDKs are available and instructions on how to use them.

Step 1: Create SSO tokens for your end users.

Before you can create an SSO token for your end users, you need to make sure you create an API key and token in Cumul.io. You can do this from your Cumul.io profile. It must own the organization with access to the integration that generates and uses this API key and token to request SSO permission. Once you’ve done that, let’s first create a Cumul.io client that will be done on the server side of the application.

const Cumulio = require("cumulio");

const client = new Cumulio({
  api_key: '<YOUR API KEY>',
  api_token: '<YOUR API TOKEN>',
});

We can now create SSO tokens for the end user. See our developer documentation for more information on this API call and required fields. SSO Token

let promise = client.create('authorization', {
  integration_id: '<THE INTEGRATION ID>',
  type: 'sso',
  expiry: '24 hours',
  inactivity_interval: '10 minutes',
  username: '< A unique identifier for your end user >',
  name: '< end-user name >',
  email: '< end-user email >',
  suborganization: '< end-user suborganization >',
  role: 'viewer',
  metadata: {}
});

Here, notice how we’ve added optional. metadata This field is where you can specify the parameters and values ​​with which you want to filter the datasets of the dashboard. The example we are going through is filtering by department so we will include it in the metadata. Ideally you would get this information from the authentication provider you use. See a detailed explanation of how we did this with Auth0.

This application will return a JSON object containing a license and token that will later be used as a key / token combination to embed dashboards on the client side.

Something else that you can optionally add here is a great CSS property. This will allow you to define a customized style and feel for each user (or user group). For the same application, the marketing dashboard for Angelina vs. Brad might look like this:

Step 2: Embed

We jumped a little further from there. We’ve created SSO tokens for end users, but we haven’t added dashboards to the application yet. Let’s take a look at it. First, you must install and import the web component.

import '@cumul.io/cumulio-dashboard';

After importing the component you can use it as if it were an HTML tag. Here’s how to embed your dashboards:

<cumulio-dashboard
  dashboardId="< a dashboard id >"
  dashboardSlug="< a dashboard slug >"
  authKey="< SSO key from step 1 >"
  authToken="< SSO token from step 1 >">
</cumulio-dashboard>

Here you will have some options. You can either provide the dashboard ID for any dashboard you want to embed, or you can provide the dashboard slug that we described in the integration setup (which is why I I highly recommend it, it is very readable to do so). You can also view our developer documentation for more detailed information on how to embed dashboards.

A good way to do this is of course just to specify the skeleton of the dashboard component in your HTML file and fill in the rest from the client side of your application. I’ve done the following, though it’s certainly not the only way.

I have added a dashboard component with the ID. dashboard:

<cumulio-dashboard id="dashboard"></cumulio-dashboard>

Then, I found this component in the client code as follows:

const dashboardElement = document.getElementById("dashboard");

I then request an SSO token from the server side of my application that returns the required key and token to add to the dashboard component. Let’s say we have a wrapper function. getDashboardAuthorizationToken() It does this for us and returns a response to the server-side SSO token request. Next, we simply fill in the dashboard component accordingly:

const authorizationToken = await getDashboardAuthorizationToken();
if (authorizationToken.id && authorizationToken.token) {
  dashboardElement.authToken = authorizationToken.token;
  dashboardElement.authKey = authorizationToken.id;
  dashboardElement.dashboardSlug = "marketing|sales|leads";
}

Notice how I explained the slugs for my dashboards in the previous steps that are part of this integration. This means I can avoid viewing and adding dashboard IDs. dashboardId As one of my parameters dashboardElement. I can only provide one slug instead. marketing, sales Or leads And I’m done! Of course you have to set up some kind of selection process in your application to decide which dashboard you embed where and when.

That’s it, logo! We’ve successfully built an integration into Cumul.io and in just a few lines of code, we’ve managed to embed its dashboards into our application; now imagine a scenario where you have the same Many applications will have to be maintained over time. Same company or separately. Whatever your scenario, I’m sure you can imagine if you have several dashboards where each of them has to go to different places and each of them has different access rights. Depends on where they are and where we are. How quickly this can get out of hand. Integrations allow you to manage it in a simple and clean way, all in one place, and as you can see, mostly from within the Cumul.io UI.

There is more you can do here that we haven’t gone into detail about. Such as adding user-specific custom themes and CSS. We haven’t even gone over how you set parameters and filters in dashboards, or how you use them from within your hosting application to have a multi-tenant setup. If you are interested, below you can find some links to useful tutorials and documents for these steps.

Write a Comment

Your email address will not be published. Required fields are marked *