Skip to main content

Embed Dashboards

Embedding dashboards

Introduction

You can embed Rill dashboards in your own applications using iframe. This allows you to use Rill dashboards as a component.

To embed a dashboard, the customer's backend needs to use a Rill service token to request an authenticated iframe URL from admin.rilldata.com. The iframe URL is then used to embed the dashboard in the customer's application. Here is a diagram of the flow:

Create a service token

Use rill cli to create a service token for your organization. You can create a new service account along with token for your organization using the following command:


rill service create <service_name> [--org "My Organization"]
caution

The service account provides admin-level access to the org and should be handled confidentially and NOT integrated in a frontend / other user-facing code.

See the reference docs for more details on managing service account and token.

Backend: Build an iframe URL

The backend needs to use the service token to request an iframe URL from admin.rilldata.com. The iframe URL is then used to embed the dashboard in the customer's application. Here are examples of how to get an iframe URL using different languages:

curl -X POST --location 'https://admin.rilldata.com/v1/organizations/<org-name>/projects/<project-name>/iframe' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <rill-svc-token>' \
--data-raw '{
"resource": "<dashboard-name>",
"user_email":"<user-email>"
}'

The API accepts the following parameters:

ParameterDescriptionRequired
resourceThe name of the dashboard to embedYes
user_emailThe email of the user to embed the dashboard forNo (either this or attributes)
attributesJson payload to be put in the access token, used to pass attributes to the dashboard for enforcing policies. When using this make sure to pass all the attributes used in your security policyNo (either this or user_email)
ttl_secondsThe time to live for the iframe URLNo (Default: 86400)

The response will contain an iframeSrc that can be used to embed the dashboard in the customer's application along with ttlSeconds for which the iframe url will be valid after which it needs to be fetched again. Here's an example response:

{
"iframeSrc": "https://ui.rilldata.com/-/embed?access_token=<token>&instance_id=<id>&kind=MetricsView&resource=<dashboard-name>&runtime_host=<runtime_host>&state=&theme=",
"runtimeHost": "<runtime_host>",
"instanceId": "<id>",
"accessToken": "<token>",
"ttlSeconds": 86400
}

Frontend: Embed the dashboard

The frontend just need to use the iframeSrc to embed the dashboard in the customer's application. Here's an example of how to embed the dashboard using iframe:

<iframe title="rill-dashboard" src="<iframeSrc>" width="100%" height="1000" style="border:0;" />

Example

Here's an example of how to create a dashboard component in a React application, this component will fetch the iframe URL from the backend and embed the dashboard in the frontend:

import React, { useEffect, useState } from 'react';

const RillDashboard = () => {
const [iframeUrl, setIframeUrl] = useState('');

useEffect(() => {
const getIframeUrl = async () => {
try {
// call the backend to get the iframe URL, see the "Backend: Build an iframe URL" section for details and examples
const response = await fetch(`/api/rill/iframe`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
resource: dashboardName,
}),
});
if (!response.ok) {
throw new Error('Network response was not ok');
}
const { iframeSrc } = await response.json().iframeSrc;
setIframeUrl(iframeSrc);
} catch (err) {
console.error(err);
}
};
getIframeUrl();
}, []);

return (
<iframe title="rill-dashboard"
src={iframeUrl}
width="100%"
height="1000"
style="border:0;"
/>
);
};

export default Dashboard;