Embedding means placing an ingestia.bi dashboard inside another website (a customer
portal, an internal system) through an <iframe>, with a signed token and an
origin allowlist. An optional JS SDK lets the host page listen to
events and push filters into the dashboard.
Example workspace: Comércio Aurora Ltda (aurora); fictitious host origin
https://portal.example.com.
How it works (overview)#
- Your backend requests an embed token (HMAC-SHA256) for a specific dashboard.
- You add an
<iframe src="/d/embed/<token>">to the host page. - The server validates Origin/Referer, and the
frame-ancestorsCSP restricts who can frame the iframe (allowlist). - (Optional)
embed-sdk.jsconnects the page to the iframe viapostMessagefor events and filters.
Prerequisites#
- A published dashboard.
- The host origin (
https://portal.example.com) on the environment's embed allowlist. - A backend able to generate the embed token (short-lived and ephemeral).
Token and channel security#
- HMAC-SHA256 token, timing-safe verification, 15-min TTL (12h ceiling), scoped to one dashboard.
- The token can carry a row scope (for example, only the user's store): it only narrows what the dashboard's policy already allows, never widens it. PII always masked. An unpublished dashboard is refused.
- The
postMessagechannel is fail-closed: a message in the wrong format is refused; the bridge pins the first valid origin from the allowlist and only accepts commands from it; replies use an explicittargetOrigin, never*. - No message carries a data row, token or secret — the SDK only exchanges
the filter state (the same information that already goes in the
?f=URL).
Step by step#
Request the origin to be allowed
In Share ▸ 2 · Embed in your app, see the Sites allowed to display the dashboard list. If
https://portal.example.comisn't on it, ask support, giving them the domain.Turn on embedding
Choose the Maximum token lifetime (recommended: 15 minutes (recommended)) and click Turn on embed. Copy the secret — "Copy the secret now — it won't be shown again."
Generate the token on the backend
Use the code under How to issue the token on your server to sign one token per page load (short TTL), with the user's row scope, if any.
Add the iframe
On the host page:
<iframe src="https://SEU-HOST/d/embed/TOKEN" style="width:100%;height:600px;border:0"></iframe>, or use the SDK.(Optional) Connect the SDK
Include
embed-sdk.js, subscribe to events (onPronto,onEstado,onErro) and send filters to the dashboard.Test
Generate test link shows the dashboard before you write any code. Then open the portal and confirm the loading, the row slice and the filters.
What the SDK offers#
- Events for the host page (e.g.,
onErro({codigo})with codes such asorigem_nao_autorizada,timeout_carregamento). - Push/read the dashboard's filter state (list, period, range, hierarchy, numeric parameters) — never raw data.
- Height adjustment and a versioned handshake (
v: 1; any other version is refused). - Layout per device: inside a narrow iframe (phone, tablet), the dashboard uses the layout the owner arranged for that device.
- TV mode (
?tv=1) does not apply to embeds; for a big screen, use the TV link.
Expected result#
- The dashboard loads inside the portal only when the origin is on the allowlist.
- Each visitor sees the RLS slice of the token the backend issued.
- Filters pushed by the host page are reflected in the dashboard; no sensitive data
travels through
postMessage.
Common mistakes#
| Symptom | Cause | What to do |
|---|---|---|
Blank iframe / origem_nao_autorizada | origin not on the allowlist | ask support to allow https://portal.example.com |
| Every token stopped working | someone clicked generate new secret or Disable | update the secret on the server / Re-enable |
| "Token expired" | the 15-min TTL ran out | generate a new token per session/page load |
| Filters ignored | origin not "pinned" correctly | make sure commands come from the allowlisted origin |
Limits and caveats#
- The origin allowlist is platform-wide, not per workspace.
- For sharing without embedding, use the public link.
Related#
Last reviewed: 2026-10-03.