Skip to Content

Component Options

Show custom charts in embeds

Let your published custom charts draw inside an embedded dashboard or metric, and allow them in your page's CSP.

A metric whose chart type is a custom chart (custom:<key>) draws that chart in the embed. The chart code runs in a sandboxed frame, never in your page.

Before you start

  • The custom chart is published in Settings > Developers > Custom charts.
  • Your company has Embedding. Custom charts are on every plan. Showing them to your own users through an embed needs Embedding, which is on the Enterprise plan.
  • The embed uses the v2 chart engine. Add ui-version="v2" or data-dbn-ui="v2". See Turn on the v2 embed design.
  • Your page’s domain is in the data app’s whitelisted domains.

Steps

  1. Save a metric with the custom chart as its chart type, on a dashboard in your data app.

  2. Turn on the v2 chart engine on the element:

    <dbn-dashboard
      token="GUEST_TOKEN"
      dashboard-id="DASHBOARD_ID"
      ui-version="v2"
      embed-flags='{"embed_ui_v2_master":true}'
    ></dbn-dashboard>
  3. Add the CSP rules below to your page, if your page sends a Content-Security-Policy.

You see the custom chart on its card, with your data.

How it loads

  1. The embed asks for the chart code: GET https://api.usedatabrain.com/api/v2/embed/custom-charts/<key>, with the guest token in X-Plugin-Token.
  2. The server checks that the token is live and that your page’s origin is whitelisted. It returns the published version only.
  3. The embed caches the code for five minutes per page, then checks again with If-None-Match.
  4. The embed creates a blob: frame with sandbox="allow-scripts". That frame creates a second blob: frame that runs the chart code.
  5. The chart gets its rows and options by postMessage. It never gets the guest token, your page’s DOM, cookies or storage.

The chart frames cannot make network requests, load remote scripts, or use the camera, microphone, location, clipboard or full screen.

CSP for your page

A blob: frame inherits your page’s CSP. Your page must allow:

DirectiveValueWhy
frame-srcblob:The two chart frames are blob: documents.
script-src'unsafe-inline'The chart code runs as an inline script in the frame.
connect-srchttps://api.usedatabrain.com (or your base-url)The embed fetches the chart code.

If your CSP has child-src and no frame-src, add blob: to child-src.

Bring your own charting

Custom charts are built in Databrain and drawn in the sandbox. A second way to change drawing is to replace a built-in chart renderer in your own code.

The plugin’s types describe that contract: DbnChartRenderer returns { update(props), dispose() }, and DbnChartEngine is { render, supports(type) }. Registration is done with registerChartRenderer and setChartEngine from @databrainhq/core/charts. That package is not published to npm, so an embed host cannot call them today.

If something goes wrong

ProblemCause
404 custom_chart.not_published: “No published custom chart “<key>”. Publish it in Settings > Developers > Custom charts.”The chart is not published, or the key belongs to another company.
401 INVALID_GUEST_TOKENThe guest token is missing, expired or revoked. Create a new one.
401 INVALID_GUEST_ORIGINThe request had no valid Origin header.
403 UNAUTHORIZED_ORIGINYour page’s domain is not whitelisted for the data app.
429More than 120 requests a minute for chart code.
The card says “This tile uses a custom chart (custom:<key>) that is not published.”Publish the chart in Settings > Developers > Custom charts.
The card says “Could not load the chart (HTTP <status>).”The request for the chart code was refused. Use the status rows above.
The card says “Chart could not load. Check the bundle and data.”The frame did not start. Check frame-src blob: and script-src 'unsafe-inline' in your CSP.

Next: Look up element attributes.