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
- The dashboard is published, and its tenant access is not None. See Publish and share.
- The tenant is registered with GOAT. See Tenants and access.
- Your backend has an endpoint that returns a viewer token. See Viewer tokens.
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
- Replace
/my-backend/embed-tokenwith the path of your backend's token endpoint. It must return the token itself, as plain text. - If your page uses a Content Security Policy with nonces, put your page's nonce in place of
YOUR_NONCEon both script tags. If your page sends no script policy at all, remove bothnonceattributes. See Content Security Policy. - Keep the script block directly after the
qc-embed-viewelement. 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-viewelement is the dashboard. Itsbase-urlis your install's address and itsdashboard-idnames 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 see | What to check |
|---|---|
Your backend gets 404 TENANT_UNKNOWN | The tenant is not registered. See Tenants and access. |
Your backend gets 403 TENANT_SUSPENDED | The tenant is registered but suspended. |
Your backend gets 401 API_KEY_INVALID | The API key is wrong or revoked. |
| A message that the element has no token provider | The script block comes directly after the element, and it runs. |
| The token is refused although your backend got one | Your endpoint returns the token itself as plain text, with a success status. |
| The dashboard is not found | It is published, its tenant access is not None, and the tenant has access. |
| Charts with no rows | The tenant id matches the values in each dataset's tenant key column exactly. |
GOAT answers the page 403 ORIGIN_DENIED | Your 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 dashboard | Your policy allows your install's address. See Content Security Policy. |