Iframe quickstart

An iframe embed is a signed Ridge URL rendered in a separate document. It needs no API key, JWT exchange, or host JavaScript to display a dashboard.

1. Generate a signed URL

Open the dashboard's Embed dialog in Ridge, choose Iframe Embed, and generate a URL. If the dashboard uses partitioned data, choose the viewer's partition before generating it. The partition is covered by the URL signature and cannot be changed by editing the URL.

See Iframe authentication for credential lifecycle and Partitioning for row-level access.

Treat the signed URL as a credential. Anyone who has it can view the scoped dashboard until you revoke it in Ridge.

2. Add the iframe

<iframe
  id="ridge-dashboard"
  src="SIGNED_RIDGE_EMBED_URL"
  title="Sales dashboard"
  width="100%"
  height="640"
  frameborder="0"
></iframe>

That is a complete integration. The dashboard's published theme is used, and Ridge handles loading its specification and data inside the frame.

3. Optional: control state from the host

Use postMessage when your own controls need to drive the dashboard. Always send to and accept messages from the iframe's exact origin.

const frame = document.querySelector("#ridge-dashboard");
const ridgeOrigin = new URL(frame.src).origin;

window.addEventListener("message", (event) => {
  if (event.source !== frame.contentWindow || event.origin !== ridgeOrigin) return;

  if (event.data?.type === "ridge:ready") {
    console.log("Dashboard ready", event.data.stateSchema);
    frame.contentWindow.postMessage(
      {
        type: "ridge:setState",
        state: { "region-menu": { filter: "EMEA" } }
      },
      ridgeOrigin
    );
  }
  if (event.data?.type === "ridge:stateChange") {
    console.log("Dashboard state", event.data.state);
  }
  if (event.data?.type === "ridge:error") {
    console.warn("Dashboard rejected a write", event.data.error);
  }
});

Your application origin must be present in Ridge's iframe origin allowlist before the frame will accept messages from it.

See Dashboard state for reads, writes, and request ids.

Revoking access

Revoke the signed URL from the dashboard's Embed dialog. Revocation affects that iframe credential without changing the dashboard or other generated URLs.