Skip to Content

Embedding Setup

Embed your first dashboard

Show a Databrain dashboard inside your app, with each customer seeing only their own data.

You make three things in Databrain, add one endpoint to your backend and one element to your page.

Before you start

  • You are an Admin or Editor in Databrain.
  • You have a dashboard to show. Note its Dashboard ID. Find a dashboard ID
  • Your company has the Enterprise plan, or Databrain turned on Embedding for it.

Steps

  1. Create the data app.

    1. Go to Data Studio > Data Apps and select Create data app.
    2. Enter an App name, for example Customer Portal.
    3. For Data app type, select Embedded. Select a Workspace.
    4. Select Create data app.
  2. Add the dashboard as an embed. The video shows this step and the snippet.

    1. Select the Embeds tab, then Add embed.
    2. Select the Workspace, keep Embed type as Dashboard and select the Dashboard.
    3. Select Create embed.
  3. Create an API token for your backend.

    1. Select the API tokens tab, then Generate API token.
    2. Enter a Name, for example Production backend, and select Generate API token.
    3. Select Copy token and store it in your backend secrets as DATABRAIN_API_TOKEN. You see the full token only once.
  4. Add a token endpoint to your backend. It creates one guest token per signed-in user.

    server.js
    app.get('/api/databrain-token', requireSignedInUser, async (req, res) => {
      const response = await fetch(
        'https://api.usedatabrain.com/api/v2/guest-token/create',
        {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env.DATABRAIN_API_TOKEN}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            clientId: req.user.companyId, // your customer company (tenant)
            dataAppName: 'Customer Portal', // exact data app name
            params: { userIdentifier: req.user.id }, // the person viewing
          }),
        }
      );
      const { token, error } = await response.json();
      if (error) return res.status(response.status).json({ error });
      res.json({ token });
    });

    What clientId must be depends on your tenancy level. See Create a guest token.

  5. Install the package in your frontend.

    npm install @databrainhq/plugin
  6. Load the web components once, in browser code.

    import '@databrainhq/plugin/web';
  7. Fetch a guest token and show the dashboard.

    const { token } = await fetch('/api/databrain-token').then((r) => r.json());
    
    const dashboard = document.createElement('dbn-dashboard');
    dashboard.setAttribute('token', token);
    dashboard.setAttribute('dashboard-id', 'revenue-overview');
    dashboard.style.display = 'block';
    dashboard.style.height = '800px';
    document.querySelector('#analytics').replaceChildren(dashboard);
  8. Add your site to the allowed domains. In the data app, select Domains, enter your domain, for example app.example.com, and select Add. The list is shared by every data app in your company.

You see the dashboard on your page, with only the rows of the signed-in user’s company. Next, check your setup before go-live.

A sample host app named Acme Analytics with its own sidebar, showing the embedded Revenue overview dashboard with a Revenue by region bar chart.
The Revenue overview dashboard embedded in a host app. Your app keeps its own navigation around it.

To see this view before you write code, open the embed’s Get snippet dialog, select Copy snippet, then Create test guest token and Preview as customer.

To show one chart instead of a whole dashboard, use <dbn-metric> with metric-id. Find a metric ID

For React, Next.js, Vue, Angular, Svelte and Solid, see Pick your framework.

If something goes wrong

  • The embed says UNAUTHORIZED_ORIGIN. The page’s domain is not on the Domains list. Add it.
  • The embed says DASHBOARD_NOT_FOUND. The dashboard-id is not an embed of this data app. Copy it from Embeds > Get snippet.
  • The token request returns 403 entitlement_required. Embedding is not on your plan. See Create a guest token.
  • The console says no dashboard-id was set or looks like a name, not an id. Set dashboard-id to the dashboard’s ID, not its name.
  • The dashboard is cut off or has no height. Give the element, or the box it sits in, a fixed height.

On this page