Iframe quickstart

Add an iframe with a signed Ridge URL to display a dashboard in your app. You do not need an API key, a token endpoint, or JavaScript.

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 URL expiration and revocation, and Partitioning for row-level access.

Treat the signed URL as a credential. Anyone who has it can view the dashboard and its permitted data until you revoke it in Ridge. An open iframe keeps working until its next token renewal; see Lifecycle and revocation.

2. Add the iframe

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

The iframe loads the dashboard and its data from Ridge, using the dashboard's published theme.

3. Optional: control state from the host

The frame sends ridge:ready once it can accept commands. Replies and events are addressed to the origin of the first message your app sends, so send a command after ridge:ready even if you only want to listen. See Host origin.

Register the listener before loading the signed URL. For this example, create the iframe from step 2 without its src attribute and set it at the end of the script:

const frame = document.querySelector("#ridge-dashboard");
const signedUrl = "SIGNED_RIDGE_EMBED_URL";
const ridgeOrigin = new URL(signedUrl).origin;
const readyTimeout = setTimeout(() => {
  console.warn(
    "No ridge:ready received. Check loading errors and that this listener ran before the frame loaded."
  );
}, 15_000);

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

  if (event.data?.type === "ridge:ready") {
    clearTimeout(readyTimeout);
    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);
  }
});

frame.src = signedUrl;

The timeout is a diagnostic. A failed load, a revoked URL, or a slow network can all prevent readiness. Inspect the iframe's network requests and browser console.

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

Revoking access

Revoke the signed URL from the dashboard's Embed dialog. The dashboard and other generated URLs remain available.