Sumboard SDK

The Sumboard SDK is a powerful tool for creating and embedding interactive dashboards into your web applications. This documentation will guide you through the installation, frontend integration, backend integration, and filter usage processes.

Sumboard dashboards can be embedded in three different ways

Simple dashboard embed: This involves displaying a dashboard in your application as you see it in the Sumboard Editor, without any predefined filters.
Embed dashboard with static token parameter: This approach involves embedding a dashboard and filtering it with a parameter that comes from your application. This is often used when you want to provide the same dashboard for multiple users from your application, and you want each user to see their own data. This is usually achieved by sending a parameter like user_id in the token.
Embed dashboard with your application filters: With this approach, you can have full control of the interactive filters for the dashboard. You can combine it with token parameters to offer your users a dashboard with their own data and have full control of the filters they can apply to it.

Installation
Simple dashboard embed
- Generating a Sumboard Token
- Simple dashboard embed demo
Embed dashboard with static token parameter
Embed dashboard with your application filters
Localize your dashboard

Installation

To install the Sumboard SDK, run the following command:

npm install @zeelix/sdk

Simple dashboard embed

Here we will show you how to embed a simple dashboard in your application using the Sumboard SDK.

This code initializes the Zeelix SDK and fetches a token from the backend server. It then initializes the Sumboard dashboard by passing the token and dashboard ID to the init() method of the SDK.

import { Zeelix } from '@zeelix/sdk';

const sumboard = new Zeelix();

fetch('<https://your-backend.com/api/token>')
  .then<{ token: string }>((response) => response.json())
  .then(({ token }) => sumboard.init({ token, dashboardId: '<DASHBOARD_ID>' }));

Replace <https://your-backend.com/api/token> with the URL of the API endpoint that your backend uses to generate tokens and <DASHBOARD_ID> with the ID of the dashboard you want to embed.

To display the dashboard in your application, add a <div> element with the specified width and height, and set the id attribute to zeelix:

<div id="zeelix" style="width: 1000px;height: 500px;"></div>

Generating a Sumboard Token

To generate a Sumboard token, create an endpoint on your backend that uses the company secret key and dashboard shared token to generate and return the token. Here's an example of how to generate a Sumboard token in a Node.js backend:

import { FiltersValues } from '@zeelix/types';
import { sign } from 'jsonwebtoken';

const st = '<DASHBOARD_SHARED_TOKEN>';
const companySecretKey = '<COMPANY_SECRET_KEY>';

const token = sign({ st }, companySecretKey);

Replace <DASHBOARD_SHARED_TOKEN> with your dashboard's shared token and <COMPANY_SECRET_KEY> with your company's secret key. Once you have the token, pass it to the Sumboard SDK's init method to initialize the SDK in your frontend application.

Simple dashboard embed demo

You can also test this code in this StackBlitz Demo

Note The demo uses a mock API to simulate fetching a token, and is for demonstration purposes only.

Embed dashboard with static token parameter

This is often used when you want to provide the same dashboard for multiple users from your application, and you want each user to see their own data.

Token type filters are initialized on the back-end as parameters, and should not be sent from the front-end. Here's an example of how to implement filters during token generation:

const user: FilterUnknown['values'] = [
  {
    value: 'user-uuid',
    label: 'FirstName, LastName',
  }
];

const params: FiltersValues = { user };

const token = sign({ st, params }, companySecretKey);

In this example, we're defining a user filter with a single value of "user-uuid" and a label of "FirstName, LastName". We then create a params object containing the user filter, and use sign from the jsonwebtoken package to generate a token that includes the params object.

When the token is used to embed a Sumboard dashboard, the user filter will be automatically applied to the dashboard.

Warning It's important to note that the security of the token should be carefully considered, especially if sensitive data is being passed in the params object.

Embed dashboard with your application filters

The Sumboard SDK supports various types of filters, which are defined by the FilterType enumeration. The basic filter structure is used as the foundation for creating specific filter types like TimeRange, Aggregation, Select, and Unknown.

Basic Filter Structure

Here is the interface for the basic filter structure:

export interface Filter<T extends FilterType, V = unknown> {
  type: T;
  place: FilterPlace;
  values: FilterValue<V>[];
  name?: string;
  order?: number;
}

The basic filter interface has the following properties:

type: Represents the type of filter (TimeRange, Aggregation, Select, or Unknown).
place: Specifies where the filter is displayed within the application, using the FilterPlace enumeration.
values: An array of filter values.
name: (optional): The name of the filter, which is displayed in the filter bar.
order: (optional): The order in which the filter should appear in the filter bar.

Here is the FilterPlace enumeration:

export enum FilterPlace {
  Apps = 'apps',
  Extern = 'extern',
  Token = 'token',
}

The FilterPlace enumeration represents where the filters are displayed and can have the following values:

FilterPlace.Apps: Filters are displayed above the charts in the application. These filters can be changed from within the application, from outside the application (via the SDK), or from the token (when the backend generates the token).
FilterPlace.Extern: Filters are outside the application. These filters can be changed from outside the application (via the SDK) or from the token (when the backend generates the token).
FilterPlace.Token: Filters that are added to the token when the token is generated by a third party. These filters can be changed only from the token (when the backend generates the token).

Filter Types

Here is the interface for the filter types:

export enum FilterType {
  TimeRange = 'time_range',
  Aggregation = 'aggregation',
  Select = 'select',
  Unknown = 'unknown',
}

TimeRange Filter (`FilterType.TimeRange`)

The TimeRange filter is used for selecting a time range. It has a value in this structure from~to[], where both from and to can be a custom range or a timestamp. The TimeRangeType type represents the various time range options supported by this filter.

Here is the interface for the TimeRange filter:

export type Time = number;

export enum CustomRange {
  Today = 'today',
  Yesterday = 'yesterday',
  LastWeek = 'lastWeek',
  LastMonth = 'lastMonth',
  Last7Days = 'last7Days',
  Last30Days = 'last30Days',
}

export type TimeRangeType =
  | CustomRange.Today
  | CustomRange.Yesterday
  | CustomRange.LastWeek
  | CustomRange.LastMonth
  | CustomRange.Last7Days
  | CustomRange.Last30Days
  | `${Time}~${Time}`
  | `${Time}~`
  | `~${Time}`;

export type FilterTimeRange = Filter<FilterType.TimeRange, TimeRangeType>;

These predefined ranges (Today, Yesterday, etc.) and custom time ranges (using ${Time}) allow you to configure the TimeRange filter according to your needs.

Aggregation Filter (`FilterType.Aggregation`)

The Aggregation filter is used for aggregating data. It has a value in this structure DateFormat[].

Here is the interface for the Aggregation filter:

export enum DateFormat {
  Hour = 'hour',
  Day = 'day',
  Week = 'week',
  Month = 'month',
  Quarter = 'quarter',
  Year = 'year',
}

export type FilterAggregation = Filter<FilterType.Aggregation, DateFormat>;

The DateFormat enumeration represents various aggregation options such as hour, day, week, month, quarter, and year. You can use the Aggregation filter to customize how your data is aggregated based on these options.

Select Filter (`FilterType.Select`)

The Select filter is used for filtering data by selected values from another query.

Here is the interface for the Select filter:

export interface FilterSelect extends Filter<FilterType.Select, (string | number)[]> {}

The Select filter allows you to filter your data based on the selected values, which can be strings or numbers, from another query. This can be useful for creating dependent filters or conditional data display based on user selections.

Unknown (Custom Filter) (`FilterType.Unknown`)

The Unknown (Custom Filter) is a filter that is allowed to be used in the FilterPlace.Extern or FilterPlace.Token

Here is the interface for the Unknown (Custom Filter):

export type FilterUnknown<T = unknown> = Filter<FilterType.Unknown, T>;

The Unknown (Custom Filter) allows you to create custom filters with user-defined value structures. This can be useful for integrating filters that are not part of the predefined filter types and can be used in external or token-based filter placement.

Filter implementation

Implementing filters during SDK initialization

To implement filters during initialization, create a filters object containing the desired filter configurations and pass it to the sumboard.init() method along with the token and dashboard ID.

Here's an example of how to implement filters on initialization:

const filters: FiltersMap<FilterType> = {
  aggregation: {
    type: FilterType.Aggregation,
    place: FilterPlace.Apps,
    values: [
      {
        value: DateFormat.Month,
        label: 'Month',
      },
    ],
  },
  timeRange: {
    type: FilterType.TimeRange,
    place: FilterPlace.Apps,
    values: [
      {
        value: CustomRange.Last30Days,
        label: 'Last 30 days',
      }
    ]
  },
  users: {
    type: FilterType.Select,
    place: FilterPlace.Apps,
    values: [
      {
        value: ['user-uuid-1', 'user-uuid-2'],
        label: 'User Name 1, User Name 2',
      }
    ]
  }
};


fetch('https://your-backend.com/api/token')
  .then<{ token: string }>((response) => response.json())
  .then(({ token }) => sumboard.init({ token, filters, dashboardId: '<DASHBOARD_ID>' }));

You can also test this code in this StackBlitz Demo

Note The demo uses a mock API to simulate fetching a token, and is for demonstration purposes only.

Changing filters after SDK initialization

To change filters after initialization, you can call the changeFilters method of the Sumboard instance. This method takes an object where each key represents the name of the filter you want to change, and the value is an object containing the updated values for that filter.

Here is an example of changing the Aggregation filter:

document.getElementById('aggregation').onchange = ({ target }) => {
  const value = (target as HTMLSelectElement).value as DateFormat;

  sumboard.changeFilters({
    aggregation: {
      type: FilterType.Aggregation,
      place: FilterPlace.Extern,
      values: [{ value }],
    },
  });
};

In this example, we're changing the aggregation filter to a new value specified by the user through an HTML select element. Note that the changeFilters method can change one or several filters at once, depending on the keys of the object passed as an argument.

You can also test this code in this StackBlitz Demo

Note The demo uses a mock API to simulate fetching a token, and is for demonstration purposes only.

Localize your dashboard

In order to provide your users with a different language, timezone and localization options, you can pass a config parameter when you generate the token on server side.

import { FiltersValues } from '@zeelix/types';
import { sign } from 'jsonwebtoken';

interface Config {
  timezone?: string,
  language?: string,
  columns?: {
    currency?: { locale: string },
    number?: { locale: string },
    date?: { locale: string },
  }
}

const st = '<DASHBOARD_SHARED_TOKEN>';

const companySecretKey = '<COMPANY_SECRET_KEY>';

const config: Config = {
  timezone: '+0200',
  language: 'en',
  columns: {
    currency: { locale: 'en' },
    number: { locale: 'en' },
    date: { locale: 'en' },
  }
};

const token = sign({ st, config }, companySecretKey);

The Config interface provides additional configuration options that can be passed during the initialization of the Sumboard Token. This interface includes the following properties:

timezone (optional): A string that represents the timezone of the data being displayed on the dashboard.
language (optional): A string that represents the language of the dashboard.
columns (optional): An object that contains configuration options for the currency, number, and date columns.

The columns property of the Config interface has the following sub-properties:

currency (optional): An object that contains a locale string that represents the currency formatting to be used for columns that contain currency data.
number (optional): An object that contains a locale string that represents the number formatting to be used for columns that contain numerical data.
date (optional): An object that contains a locale string that represents the date formatting to be used for columns that contain date data.

@zeelix/sdk

Sumboard SDK

Sumboard dashboards can be embedded in three different ways

Table of Contents

Installation

Simple dashboard embed

Generating a Sumboard Token

Simple dashboard embed demo

Embed dashboard with static token parameter

Embed dashboard with your application filters

Basic Filter Structure

Filter Types

TimeRange Filter (`FilterType.TimeRange`)

Aggregation Filter (`FilterType.Aggregation`)

Select Filter (`FilterType.Select`)

Unknown (Custom Filter) (`FilterType.Unknown`)

Filter implementation

Implementing filters during SDK initialization

Changing filters after SDK initialization

Localize your dashboard

Readme

Keywords

Package Sidebar

Install

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@zeelix/sdk

Sumboard SDK

Sumboard dashboards can be embedded in three different ways

Table of Contents

Installation

Simple dashboard embed

Generating a Sumboard Token

Simple dashboard embed demo

Embed dashboard with static token parameter

Embed dashboard with your application filters

Basic Filter Structure

Filter Types

TimeRange Filter (FilterType.TimeRange)

Aggregation Filter (FilterType.Aggregation)

Select Filter (FilterType.Select)

Unknown (Custom Filter) (FilterType.Unknown)

Filter implementation

Implementing filters during SDK initialization

Changing filters after SDK initialization

Localize your dashboard

Readme

Keywords

Package Sidebar

Install

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

TimeRange Filter (`FilterType.TimeRange`)

Aggregation Filter (`FilterType.Aggregation`)

Select Filter (`FilterType.Select`)

Unknown (Custom Filter) (`FilterType.Unknown`)

Weekly Downloads