Skip to main content

Embed in your product

Embed a dashboard

Put a published dashboard on a page of your application.

To embed a dashboard, you place GOAT's dashboard element on your page and give it a way to get a viewer token from your backend. The dashboard then draws inside your page, showing only the rows of the viewer's tenant.

Before you start​

Copy the snippet​

Open the published dashboard's page and choose Publish & share. Under Put it on your site, choose Copy. Copy works only once the dashboard is published. The snippet already holds your install's address and the dashboard's id:

<script src="https://analytics.example.com/embed/qc-embed.js" nonce="YOUR_NONCE"></script>
<!-- Add theme-id="default-light" to wear a theme of your choice; without it the dashboard wears its own. -->
<qc-embed-view base-url="https://analytics.example.com" dashboard-id="dash_abc"></qc-embed-view>
<script nonce="YOUR_NONCE">
{
// Your backend mints the viewer token; replace the URL with your endpoint.
const view = document.currentScript.previousElementSibling;
if (view?.localName !== 'qc-embed-view') throw new Error('qc-embed-view must come directly before this script');
const mint = () => fetch('/my-backend/embed-token').then((r) => {
if (!r.ok) throw new Error('token endpoint ' + r.status);
return r.text();
});
let token;
view.getToken = (force) => {
if (!token || force) {
const p = (token = mint());
p.catch(() => { if (token === p) token = undefined; });
}
return token;
};
}
</script>

Adjust it for your page​

  1. Replace /my-backend/embed-token with the path of your backend's token endpoint. It must return the token itself, as plain text.
  2. If your page uses a Content Security Policy with nonces, put your page's nonce in place of YOUR_NONCE on both script tags. If your page sends no script policy at all, remove both nonce attributes. See Content Security Policy.
  3. Keep the script block directly after the qc-embed-view element. It finds its element that way, so you can paste the snippet once for each dashboard on the same page.

What the snippet does​

  • The first script tag loads the embed script from your install. Always load it from there, not from a copy: your install's script is the one that matches its version.
  • The qc-embed-view element is the dashboard. Its base-url is your install's address and its dashboard-id names the dashboard.
  • The script block gives the element a way to get a token. It asks your endpoint once, reuses the token, and asks again only when GOAT says the token has expired.

The dashboard shows a loading state until it has a token. If the element is given no way to get a token within a few seconds, it says so.

Choose a theme​

Without a theme, the dashboard wears the theme it was built with. To choose one, add theme-id to the element: default-light and default-dark are built in, and a custom theme's id is shown under its name in the builder's theme editor. See Embed options.

Remove the dashboard​

Removing the element from the page stops its requests. When you mount dashboards from code, call destroy() on the mounted view. See Embed SDK.

Common problems​

When the view ends on a token message, look first at what GOAT answered your backend's token request.

What you seeWhat to check
Your backend gets 404 TENANT_UNKNOWNThe tenant is not registered. See Tenants and access.
Your backend gets 403 TENANT_SUSPENDEDThe tenant is registered but suspended.
Your backend gets 401 API_KEY_INVALIDThe API key is wrong or revoked.
A message that the element has no token providerThe script block comes directly after the element, and it runs.
The token is refused although your backend got oneYour endpoint returns the token itself as plain text, with a success status.
The dashboard is not foundIt is published, its tenant access is not None, and the tenant has access.
Charts with no rowsThe tenant id matches the values in each dataset's tenant key column exactly.
GOAT answers the page 403 ORIGIN_DENIEDYour install limits which sites may embed, and your page's exact address (scheme, host, and port) is not on its list.
The page's security policy blocks the dashboardYour policy allows your install's address. See Content Security Policy.
GOAT documentation

Type to search.