# Embed SDK

The embed script's elements, options, and methods.

The embed script puts a GOAT dashboard on your page. Every install serves it at `/embed/qc-embed.js` on its own address. Load it from your install, not from a copy, so it always matches your install's version.

```html
<script src="https://analytics.example.com/embed/qc-embed.js"></script>
```

It offers the `qc-embed-view` element and the `QcEmbed.mount` function. Both draw the same dashboard. For a worked example, see [Embed a dashboard](../embed/embed-a-dashboard.md).

## The `qc-embed-view` element

```html
<qc-embed-view id="sales" base-url="https://analytics.example.com" dashboard-id="dash_abc"></qc-embed-view>
<script>
  let token = null;
  document.getElementById('sales').getToken = async (force) => {
    if (token && !force) return token;
    const r = await fetch('/my-backend/embed-token');
    if (!r.ok) throw new Error('token endpoint ' + r.status);
    token = await r.text();
    return token;
  };
</script>
```

| Attribute | Property | What it sets |
|---|---|---|
| `base-url` | `baseUrl` | Your install's address. |
| `dashboard-id` | `dashboardId` | The dashboard to show. Required. |
| `theme-id` | `themeId` | A theme for the dashboard to use. |
| `eager` | `eager` | Load every chart at once, rather than as it scrolls into view. |
| `nonce` | none | Your page's Content Security Policy nonce, if the script tag does not carry it. |
| none | `theme` | `'light'` or `'dark'`, the appearance of the embed's own controls only. |
| none | `filters` | Filters set on load, described below. |
| none | `getToken` | The function that gives the element a viewer token. Required. |

A property, when set, takes the place of its attribute. Changing an attribute or a property starts the dashboard again.

### `getToken`

The element calls `getToken(force, stale)` for every request it makes, as in the sample above.

- Return a token you already have, unless `force` is `true`.
- `force` is `true` when GOAT refused a token as expired. `stale` is that token. Get a new one.
- If the promise fails, the next request calls `getToken` again.

The snippet from Publish & share holds a `getToken` that does all of this. If no `getToken` is set within 3 seconds, the element says "This embed has no token provider." Setting it later still starts the dashboard.

## `QcEmbed.mount`

```js
const view = QcEmbed.mount('#sales', {
  dashboardId: 'dash_abc',
  tokenProvider: () =>
    fetch('/my-backend/embed-token').then((r) => {
      if (!r.ok) throw new Error('token endpoint ' + r.status);
      return r.text();
    }),
});
```

The first argument is a CSS selector or an element. `mount` returns at once, without waiting for the network. Mounting into an element that already holds a dashboard replaces it.

| Option | What it sets |
|---|---|
| `dashboardId` | The dashboard to show. Required. |
| `tokenProvider` | A function that returns a viewer token, or a promise of one. Required. |
| `baseUrl` | Your install's address. Defaults to the address the script loaded from. |
| `themeId` | A theme for the dashboard to use. |
| `theme` | `'light'` (the default) or `'dark'`, the appearance of the embed's own controls only. |
| `filters` | Filters set on load. |
| `eager` | `true` to load every chart at once. |
| `nonce` | Your page's Content Security Policy nonce, if the script tag does not carry it. |

### `tokenProvider`

`tokenProvider()` takes no arguments. The script calls it the first time a token is needed, and again when GOAT refuses a token as expired. A request that is still refused with a fresh token ends the session.

When a call fails, the script tries again:

| Attempt | When |
|---|---|
| First | At once |
| Second | Half a second after the first fails |
| Third | A second and a half after the second fails |

A call fails when it throws, when its promise rejects, or when it does not answer within 15 seconds. If the third attempt fails, the session ends.

Throw when your token endpoint answers with an error, as the sample does. Otherwise the script sends the error page to GOAT as if it were a token, and does not retry.

### `destroy()`

```js
view.destroy();
```

Removes the dashboard, cancels its requests, and ends its session. Calling it again does nothing, and it never touches another dashboard on the page. After `destroy()`, the `tokenProvider` is never called again.

## Filters set on load

`filters` is an object keyed by filter id:

| Form | Example |
|---|---|
| Values | `{ "flt_region": { "values": ["West", "East"] } }` |
| Range | `{ "flt_amount": { "range": { "from": 100, "to": 500 } } }` |
| Preset | `{ "flt_date": { "preset": "LAST_30_DAYS" } }` |

Anyone viewing the page can change filters set on load, including a filter the author hid. Never use them to keep data from a viewer. What a viewer may see is set by the viewer token and the tenant's access. See [Embed options](../embed/embed-options.md#filters-set-on-load).

## The `actionclick` event

The element sends `actionclick` when a viewer runs a chart action. It bubbles, and `preventDefault()` stops the action.

| Field of `event.detail` | What it holds |
|---|---|
| `dashboardId`, `elementId`, `actionId` | Where the click happened. |
| `kind` | The action: `'filter'`, `'goto'`, `'link'`, and others. |
| `values` | The values clicked, as `{ column, value }`. |
| `target` | For Go to, `{ kind, id }`; for a link, `{ url }`. |

## What the viewer sees

While it starts, the dashboard shows "Loading dashboard…". A chart that fails to load shows its error in place, with a way to retry. When the whole dashboard cannot be shown, it shows one of these messages:

| Message | Cause |
|---|---|
| This dashboard is not available. It may have been removed, or you may not have access to it. | The dashboard is not published, does not exist, or the tenant has no access. |
| This account is suspended. Contact whoever shared this dashboard. | The tenant is suspended. |
| This dashboard could not be shown because the account was not recognised. Contact whoever shared it. | The tenant is not registered. |
| You do not have access to this dashboard. Contact whoever shared it. | GOAT refused the dashboard's first read for a reason not listed above, such as a page whose site is not on the install's allowed sites (`403 ORIGIN_DENIED`; see [Install settings](settings.md#allowed-sites)). |
| Your session ended and could not be renewed. Reload the page to continue. | Your token function failed three times, or GOAT refused the new token it gave. Check your token endpoint. |
| Nothing here yet | The published dashboard has no content. |

Some refusals belong to one chart, and show in that chart's place while the rest of the dashboard works. A chart whose dataset has no [tenant key](../build-dashboards/connect-data.md#the-tenant-key) and is not shared with every tenant shows "This data is not set up for your account yet. Contact the owner of this dashboard." (`403 RLS_REQUIRED`).

## Several dashboards

Each element or mount keeps its own session. Paste one snippet per dashboard, or call `mount` once per target.

## Version

`QcEmbed.version` holds the version of the script your install serves.
