Reference
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.
<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.
The qc-embed-view element
<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
forceistrue. forceistruewhen GOAT refused a token as expired.staleis that token. Get a new one.- If the promise fails, the next request calls
getTokenagain.
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
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()
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.
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). |
| 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 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.