Quick start-Quick BI(Quick BI)-阿里云帮助中心

Many companies build their own enterprise portal system or data analytics platform and embed Quick BI to create a unified, integrated analytics experience. For example, you can embed the Quick BI dashboard editing page into your own system. This allows users to edit a dashboard and return to your application without leaving its environment.

The Quick BI embedded JS SDK lets you quickly integrate specific pages into your application. You can use configuration parameters to customize the page content and navigation logic.

Limitations

The embedded JS SDK is available only in the Professional Edition.
To embed private pages that require a logon, you must first integrate your system's user accounts with your Alibaba Cloud account. This integration enables seamless logon for users as they navigate between systems. For instructions, see Alibaba Cloud SSO. You can embed public pages, such as shared dashboards or spreadsheets, and pages accessed with an access ticket, without this integration.
Currently, you can only embed specific Quick BI pages, including Workbench, Template Marketplace, My Dashboards, Subscription Management, Monitoring and Alarms, Datasets, Data Entry, Data Management, Data Preparation, Dashboard, Spreadsheet, DataV, Data Portal, Ad Hoc Analysis, and Self-Service Data Retrieval. For a complete list, see the Route Key List. You can customize features such as the displayed content and the destination URL for the back button.

Procedure

In addition to embedding with an iframe, Quick BI provides the embedded JS SDK for a more developer-friendly integration. The SDK lets you customize embedding features, listen for events, and invoke actions based on your application's needs. The following steps demonstrate how to embed the dashboard editing page.

Note

Customizing features, events, and actions is not supported with iframe embedding. These configurations are only available through the embedded JS SDK.

Step 1: Set up the environment

Before you begin, you should have an intermediate understanding of HTML, CSS, and ES2015 JavaScript. You also need to install Node.js. Visit the official Node.js website to download and install Node.js version 20 or later. After installation, run the following command to verify the installation:

node -v

Step 2: Install the npm package

Before you can use the embedded JS SDK, you must install its npm package. Quick BI provides different npm packages for various development environments. Choose and install the package that matches your environment.

For a vanilla JavaScript (no framework) environment
```
npm install @quickbi/bi-embed-client
```

For a React framework environment

npm install @quickbi/bi-embed-client-react

For a Vue 2 framework environment

npm install @quickbi/bi-embed-client-vue2

For a Vue 3 framework environment

npm install @quickbi/bi-embed-client-vue

Step 3: Develop the embedded page

The implementation varies depending on your development environment.

JavaScript environment (no framework): Create an EmbedClient instance from the EmbedClient class and use it to render the Quick BI dashboard editing page in your host system.

import { EmbedClient, EmbedRouteKey } from '@quickbi/bi-embed-client';

const embedClient = new EmbedClient({
  src={
    origin: 'xxx',  // Host for accessing Quick BI
    page: EmbedRouteKey.dashboardEdit,  // EmbedRouteKey for the dashboard editing page
    // Query parameters for the Quick BI dashboard page
    search: {
        workspaceId: 'xxx',  // workspace ID
        id: 'xxx',  // resource ID
    }
  }
})

embedClient.render(document.getElementById('container'))

React framework environment (Recommended): You can embed content by rendering the EmbedComponent component. This component has built-in logic to create an embedded client instance and automatically re-render.

import React from 'react';
import ReactDOM from 'react-dom';
import { EmbedComponent, EmbedRouteKey } from '@quickbi/bi-embed-client-react';

const Demo: React.FC = () => {
  return (
    <EmbedComponent
      src={
        origin: 'xxx',  // Host for accessing Quick BI
        page: EmbedRouteKey.dashboardEdit,  // EmbedRouteKey for the dashboard editing page
        // Query parameters for the Quick BI dashboard page
        search: {
          workspaceId: 'xxx',  // workspace ID
          id: 'xxx',  // resource ID
        }
      }
    />
  )
}

ReactDOM.render(<Demo />, document.querySelector('.container'))

Vue 2 framework environment: Directly import the EmbedComponent component, which by default implements the logic for creating an embedded client instance and responsive rendering.

<template>
  <EmbedComponent 
    :src="embedSrc" 
  />
</template>
<script lang="ts">
import Vue from 'vue'
import {
  EmbedComponent,
  EmbedRouteKey,
} from '@quickbi/bi-embed-client-vue2'

export default Vue.extend({
  name: 'SDK',
  components: {
    EmbedComponent
  },
  data() {
    return {
       embedSrc: {
        origin: 'xxx',  // Host for accessing Quick BI
        page: EmbedRouteKey.dashboardEdit,  // EmbedRouteKey for the dashboard editing page
        // Query parameters for the Quick BI dashboard page
        search: {
          workspaceId: 'xxx',  // workspace ID
          id: 'xxx',  // resource ID
        }
      },
    }
  },
})
</script>

Vue 3 framework environment: Directly import the EmbedComponent component, which by default implements the logic for creating an embedded client instance and for reactive rendering.

<script setup lang="ts">
import {
  EmbedRouteKey,
  EmbedComponent,
} from "@quickbi/bi-embed-client-vue";
import type { EmbedSrcUnion } from "@quickbi/bi-embed-client-vue";
import { ref } from "vue";

const embedSrc = ref<EmbedSrcUnion>({
  origin: 'xxx',  // Host for accessing Quick BI
  page: EmbedRouteKey.dashboardEdit,  // EmbedRouteKey for the dashboard editing page
  // Query parameters for the Quick BI dashboard page
  search: {
    workspaceId: 'xxx',  // workspace ID
    id: 'xxx',  // resource ID
  }
});

</script>

<template>
  <EmbedComponent
    :src="embedSrc"
  />
</template>

References

For a detailed introduction to the embedded client instance and development methods, see Basic Concepts and the Embedded JS SDK API.
To better understand how to use the embedded JS SDK, see the Development Examples.
If you encounter any issues during development, see the FAQ.