# 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](../build-dashboards/publish-and-share.md).
- The tenant is registered with GOAT. See [Tenants and access](tenants-and-access.md).
- Your backend has an endpoint that returns a viewer token. See [Viewer tokens](viewer-tokens.md).

## 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:

```html
<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](content-security-policy.md).
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](embed-options.md).

## 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](../reference/embed-sdk.md).

## 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](tenants-and-access.md). |
| 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](content-security-policy.md). |
