Embed into your application

ℹ️

You need an API key & token. Create this pair in Luzmo in your profile settings .

Generate an Authorization token

In this step, your server-side code makes an API request to Luzmo to get a temporary Authorization token. The result of this request is a key/token combination that will be used to in step 2 to securely embed the dashboard in your application/platform.

The API request is a 'create' request for an Authorization token . In this API call we use the Integration id that we created before (see Set up an Integration ).

Replace with your API key & token and integration_id and fill in the user's details

create_authorization.js

Shell

Node

Java

.NET

Python

PHP

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
    api_key: "< Your API key >",
    api_token: "< Your API token >",
    host: "< https://api.luzmo.com (default) or https://api.us.luzmo.com or your VPC-specific address >"
});

let promise = client.create("authorization", {
  type: "sso",
  expiry: "24 hours",
  inactivity_interval: "10 minutes",
  username: "< A unique and immutable identifier for your user >",
  name: "< user name >",
  email: "< user email >",
  suborganization: "< a suborganization name >",
  integration_id: "< integration id >",
  role: "viewer"
});

promise.then(function(result){
  // return the result to the client
})

Property	Description
type STRING required	`sso` Use the value 'sso' for embedding a dashboard.
expiry DATE (RFC 3339) OR STRING required	Date/time when this authorization will cease working. To promote better security practices this property is required and enforced with a maximum expiry date of 1 year. It is advised to only use short-living tokens (max. 24 hours) for maximum security.
inactivity_interval INTEGER OR STRING	Duration of inactivity after which the token is prematurely invalidated. You can use this to invalidate tokens quickly when the session is ended (eg. all open dashboards are closed). If specified, a minimum value of 2 minutes is enforced to avoid undesired invalidation of a token due to e.g. missing a heartbeat signal sent by our server. Defaults to 0 (i.e. no inactivity_interval).
username STRING required	Identifies the user uniquely and immutably. This should correspond to eg. the primary key for the user on your end. If it changes, the user will not have access to their previously created content anymore. So don't use eg. an e-mail address if those can change in your platform! This will also be used to uniquely identify a Monthly Active Viewer (MAV) for your Organization.
name STRING required	The full name of the user (i.e. First name and Last name). This will be used in our UI.
email STRING required	The email address of the user. This will be used in our UI.
suborganization STRING required	Each SSO token should be in a suborganization. The suborganization determines which other users they can see & interact with. It is required to avoid accidentally forgetting to set it which would cause all users to see each other! If you want totally isolated users, set it to the unique username.
integration_id UUID required	The UUID of the integration that the SSO token should have access to.
role STRING required	The role of the user for who you are making the authorization request. More information on the different roles: "viewer" SSO users that should only be able to view and interact with one or more dashboards, variants, and duplicates. "designer" SSO users that should be able to create, edit, view and interact> with one or more dashboards, variants, and duplicates. "owner" SSO users that should be able to create, edit, view and interact with one or more dashboards, variants, and duplicates, and next to that they should be able to favorite dashboard variants for other SSO users within their suborganization. More info under Embedded Dashboard Editor.

For a list of all properties that you can use in the request, check Authorization in the Core API.

The request returns a JSON object that contains an authorization id & token. This is the key/token combination that will be used in our next step (client-side) to embed the dashboard in a secure way.

Response

json

{
  "type": "sso",
  "id": "< the SSO authorization key >",
  "token": "< the SSO authorization token >",
  "user_id": "< a uuid used on our end to identify the SSO user >"
  // ...
}

ℹ️

This first part needs to happen server-side. This is for security reasons: you do not want to expose your API key & token client-side, as that would mean that users would be able to change filters or grant access to your securables (dashboard and/or datasets) themselves. Remember: Never use your API key and token client-side!

Embed the dashboard

To embed a dashboard in your webpage, we use the Embed Libraries .

First you should install the appropriate component library in your frontend. We have a Web component , React component , React Native component , Angular component and Vue.js component which are available via npm package manager.

In this step we'll use the SSO key and token from step 1 to securely embed a dashboard in your frontend by referencing it with its id or slug.

ℹ️

A dashboard slug is defined when associating a dashboard with the integration and makes it easy to switch embedded dashboards in your application without having to change any code: you can replace the dashboard and the slug will then dynamically point towards the new dashboard!

You can optionally retrieve a list of accessible dashboards (associated with the integration that the SSO token has access to) to dynamically provide them to your users in e.g. a sidebar in your application's frontend.

Installing the component

All frontend components are available via npm !

Install the web component via npm package manager by running the following command in your command line interface. It's recommended to use npm to ensure you can easily get the latest version of our component when available!

Command Line

Web component

Angular

React

React Native

Vue

npm i @luzmo/embed

In case your application does not support installing one of our components via npm , the Web component's minified javascript library can also be dynamically imported as a script using the code below.

Web component

Angular

React

React Native

Vue

<!--
You can (programmatically) retrieve the latest version via this link:
https://cdn.luzmo.com/js/luzmo-embed/latest-version.json
-->
<script
  defer
  src="https://cdn.luzmo.com/js/luzmo-embed/<WEB_COMPONENT_VERSION>/luzmo-embed.min.js"
  charset="utf-8"
></script>

Embedding a dashboard

:::langSpecific{lang=web type=frontend} 2. Import the component in a JavaScript module.

index.js

Web component

Angular

React

React Native

Vue

import '@luzmo/embed';

You can also import the component in an HTML page.

index.html

Web component

Angular

React

React Native

Vue

<script type="module">
  import './node_modules/@luzmo/embed/index.js';
</script>
<!-- OR -->
<script
  type="module"
  src="./node_modules/@luzmo/embed/index.js">
</script>

Add the Luzmo component to your HTML page.

index.html

Web component

Angular

React

React Native

Vue

<!--
Clients on our US multi-tenant application environment,
or a dedicated instance on a specific VPC, should specify:
- appServer="https://app.us.luzmo.com/" (or your VPC-specific address)
- apiHost="https://api.us.luzmo.com/" (or your VPC-specific address)
-->
<luzmo-embed-dashboard
  appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
  apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
  authKey="< SSO authorization key >"
  authToken="< SSO authorization token >"
  dashboardId="< dashboard id you want to embed >"
  dashboardSlug="< instead of dashboardId: a dashboard slug as specified in the Integration. >"
></luzmo-embed-dashboard>

:::

:::langSpecific{lang=angular type=frontend} 2. Import the NgxLuzmoDashboardModule in your NgModule

app.module.ts

Web component

Angular

React

React Native

Vue

import { NgxLuzmoDashboardModule } from '@luzmo/ngx-embed';

@NgModule({
  // ...
  imports: [
    // ...,
    NgxLuzmoDashboardModule,
    // ...
  ],
  // ...
})

Add the Luzmo component in your Angular page

app.component.html

Web component

Angular

React

React Native

Vue

/*
Clients on our US multi-tenant application environment,
or a dedicated instance on a specific VPC, should specify:
- [appServer]="'https://app.us.luzmo.com/'" (or your VPC-specific address)
- [apiHost]="'https://api.us.luzmo.com/'" (or your VPC-specific address)
*/
<luzmo-dashboard
  [appServer]="'< Luzmo App server, defaults to https://app.luzmo.com >'"
  [apiHost]="'< Luzmo API server, defaults to https://api.luzmo.com >'"
  [authKey]="'< SSO authorization key >'"
  [authToken]="'< SSO authorization token >'"
  [dashboardId]="'< dashboard id you want to embed >'"
  [dashboardSlug]="'< instead of dashboardId: a dashboard slug as specified in the Integration. >'"
></luzmo-dashboard>

:::

:::langSpecific{lang=reactnative type=frontend} 2. Minimal required parameters to securely embed a dashboard in a React Native application

Dashboard.js

Web component

Angular

React

React Native

Vue

import LuzmoDashboardComponent from '@luzmo/react-native-embed';
// ...

  function LuzmoWrapper() {
    // ...

    /*
    Clients on our US multi-tenant application environment,
    or a dedicated instance on a specific VPC, should specify:
    - appServer="https://app.us.luzmo.com/" (or your VPC-specific address)
    - apiHost="https://api.us.luzmo.com/" (or your VPC-specific address)
    */
    return (
      <LuzmoDashboardComponent
        ref={ref}
        appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
        apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
        authKey="< SSO authorization key >"
        authToken="< SSO authorization token >"
        dashboardId="< dashboard id you want to embed >"
        dashboardSlug="< instead of dashboardId: a dashboard slug as specified in the Integration. >"
      ></LuzmoDashboardComponent>
    );
  }

:::

:::langSpecific{lang=vue type=frontend} 2. Minimal required parameters to securely embed a dashboard in a Vue 3 application

main.js

Web component

Angular

React

React Native

Vue

import { createApp } from 'vue';
import App from './App.vue';
import VueLuzmoDashboard from '@luzmo/vue-embed';
...

const app = createApp(App);
...

// Defines the component at app level
app.use(VueLuzmoDashboard);
...

app.mount('#app');

You can also use our Vue component in your Vue 2 application

main.js

Web component

Angular

React

React Native

Vue

import Vue from 'vue';
import App from './App.vue';
import VueLuzmoDashboard from '@luzmo/vue-embed/vue2';
// ...

Vue.use(VueLuzmoDashboard);
// ...

new Vue({
  render: (h) => h(App),
}).$mount('#app');

In your HTML template of your Vue application

Dashboard.vue

Web component

Angular

React

React Native

Vue

<template>
  ...
  <!--
  Clients on our US multi-tenant application environment,
  or a dedicated instance on a specific VPC, should specify:
  - :appServer="https://app.us.luzmo.com/" (or your VPC-specific address)
  - :apiHost="https://api.us.luzmo.com/" (or your VPC-specific address)
   -->
  <luzmo-dashboard
    ref="dashboardInstance"
    appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
    apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
    authKey="< SSO authorization key >"
    authToken="< SSO authorization token >"
    dashboardId="< dashboard id you want to embed >"
    dashboardSlug="< instead of dashboardId: a dashboard slug as specified in the Integration. >"
  ></luzmo-dashboard>
</template>

:::

Property	Description
appServer STRING	Tenancy of Luzmo app to connect to. Defaults to 'https://app.luzmo.com/'. For US multi-tenant application, set `appServer` to 'https://app.us.luzmo.com/'. For dedicated VPC environments, you should point towards your VPC-specific address.
apiHost STRING	Tenancy of Luzmo API to connect to. Defaults to 'https://app.luzmo.com/'. For US multi-tenant application, set `apiHost` to 'https://app.us.luzmo.com/'. For dedicated VPC environments, you should point towards your VPC-specific address.
authKey UUID	The authorization key (i.e. "id") from the response of the authorization request in your backend.
authToken STRING	The authorization token from the response of the authorization request in your backend.
dashboardId UUID	This is the id of the dashboard that you want to embed. Specify either* the dashboardId or dashboardSlug property.*
dashboardSlug STRING	Instead of specifying a dashboardId, you can alternatively specify a dashboard slug. The slug is defined when associating a dashboard with an Integration. Specify either* the dashboardId or dashboardSlug property.*

For a list of all frontend component properties, take a look here .

That's it, with these steps you securely embed a dashboard in your application/platform!

Did this page help you?

Yes