Docs › Share
Embedding reports in another site
Show a saved report inside another website, in an <iframe>: on a public page for anyone, on an intranet page for people who already have access, or inside your own application for its users. An embedded report is the report in Dash view, read-only, filling its frame, with Print as its one action. Embedding is part of the Ultimate plan.
The three ways to embed#
| Way | Who sees the report | How they are identified | Who sets it up |
|---|---|---|---|
| Public | Anyone who can see the page it is on | Nobody: it is the report's public link, in a frame | Someone with Manager access to the report (the report must be public) |
| Signed in | People who can already open the report: members with access, and guests it was shared with | They sign in to Insight FastPass in a small window; the frame then shows the report as them | Someone with Manager access to the report turns on embedding for it |
| Through an app | Your application's own users | Your application's server signs in as an app (OAuth client credentials) and asks for a token that shows the report as one named workspace member or guest | The workspace owner or an admin registers the app under Security |
Whichever way you pick, nothing in the frame can change the report: there is no Save, no editing and nothing to share. Filters, slicers and bookmarks work, and are forgotten when the page closes.
Public embeds#
A public embed is the report's public link shown in a frame. It opens for anyone who can see the page, so only use it for a report that is public anyway.
- Make the report public (the Share dialog's Public link section, Anyone with the link can view).
- Open the Share dialog's Embed section and pick Public. Choose a bookmark to open at, a theme and whether to show the toolbar, then Copy the snippet.
- Paste it into your page:
<iframe
src="https://InsightFastPass.com/embed/r/<link code>"
title="Sales dashboard"
width="100%" height="600"
sandbox="allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox"
allow="clipboard-write"
loading="lazy"
referrerpolicy="strict-origin-when-cross-origin"
style="border: 0"></iframe>
The link's tracked copies work here too (?via=<tag>), and every open counts as a visit to the link, as it does in a browser tab. To stop the embed, make the report private, reset its link, or let the link's end date pass: the frame shows "This report isn't available" at its next renewal, within about 12 minutes.
Signed-in embeds#
A signed-in embed shows a report to people who could open it in Insight FastPass anyway: members who have access to it, and guests it was shared with by email. Each person sees it as they would in the app, with their own row access.
- In the Share dialog's Embed section, pick Signed in and turn on embedding for the report (Manager access). It is off for every report until someone turns it on.
- Copy the snippet: the same
<iframe>as above, withsrc="https://InsightFastPass.com/embed/w/<workspace id>/<report id>".
What a viewer sees:
- The frame says Sign in to view this report with a Sign in button.
- The button opens a small Insight FastPass window (a popup, on our own site with its address bar showing). Signed out, they sign in there as usual; a guest who hasn't registered yet can register there with the address the report was shared with.
- The window asks "Open report on site as name?" with Continue, and Not you? Sign in as someone else. If the workspace's security settings ask for an authenticator code or a recent sign-in, the window asks for it as the app does.
- Continue closes the window, and the report opens in the frame.
The frame's toolbar shows who is signed in, with Not you? to sign out of the frame. The sign-in lasts up to 12 hours (less if the workspace's security settings ask for a sign-in or a code more often), and ends when the page is closed or reloaded: the next visit is one more click on Sign in, which passes straight through while the person is still signed in to Insight FastPass.
Someone who can't open the report sees "You don't have access to this report. Ask whoever shared it with you." Removing their access, removing them from the workspace, or turning off embedding for the report ends their embedded session within a few minutes.
Allowed sites#
By default a public or signed-in embed can be shown on any site. To limit it, list the sites under Allowed sites in the Embed section: exact origins such as https://intranet.example.com (or http://localhost:4500 while testing), at most 20. A frame on any other site then shows "This report can't be shown on this site".
The frame learns which site it is on from the browser. Chrome, Edge and Safari always say; Firefox says only when the host page sends its address, which the snippet's referrerpolicy attribute and embed.js both make sure of. With a list set and no way to tell, the frame shows "This site can't be checked".
Allowed sites limit where the frame shows. They don't make a public report less public: its link still opens in a browser tab for anyone who has it.
Embedding through an app#
Through an app, your application decides who its user is and which slice of the report they see; Insight FastPass shows the report as a workspace member or guest you registered for it. Think of a customer portal where each customer sees their own rows of one dashboard, or an intranet that shows a dashboard to staff who have no Insight FastPass account.
The pieces:
- An embed client, registered by the workspace owner or an admin under Security (with an authenticator confirmation). It lists the reports it may show, the sites (origins) its pages run on, the members or guests it may act as (never the owner or an admin), and optionally the row access groups it may name. A request for anything outside those lists is refused.
- Your server keeps the client's credentials, gets a short-lived access token, and asks for an embed token for one report, one user and one site.
- Your page loads
embed.js, which makes the frame and hands it the embed token. The token never appears in a URL.
The recommended set-up is one Viewer seat made for the purpose per audience, and, to show one report per customer, one row access group per customer named in each request.
1. Get an access token#
POST https://dataapi.InsightFastPass.com/api/v1/EmbedClient/Token with the OAuth 2.0 client credentials grant. Use either a client secret (client_secret_basic):
curl https://dataapi.InsightFastPass.com/api/v1/EmbedClient/Token \
-u "ifpc_yourClientId:ifps_yourClientSecret" \
-d grant_type=client_credentials -d scope=embed
or, recommended for production, a signed assertion from a key pair whose public key you registered on the client (private_key_jwt, RFC 7523). The assertion is a JWT signed with your private key (ES256 or RS256), with iss and sub your client id, aud the token URL above, exp at most 5 minutes ahead and a unique jti, and kid in its header naming the registered key:
curl https://dataapi.InsightFastPass.com/api/v1/EmbedClient/Token \
-d grant_type=client_credentials -d scope=embed \
-d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
-d client_assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6...
The answer:
{ "access_token": "...", "token_type": "Bearer", "expires_in": 300, "scope": "embed" }
The access token lasts five minutes and is good only for the next call. Errors follow OAuth 2.0: invalid_client (an unknown client, a wrong or expired secret, or a bad assertion: one answer for all), invalid_grant, invalid_scope, and unauthorized_client (the client is disabled, or the workspace isn't on Ultimate).
A client may have two live secrets at once, so you can add a new one, deploy it, and then remove the old one. Each secret is shown once when it is made, and has an end date (one year by default, two at most).
2. Get an embed token#
curl https://dataapi.InsightFastPass.com/api/v1/EmbedClient/CreateEmbedToken \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "reportId": 123, "subject": { "emailAddress": "portal-viewer@yourcompany.example" },
"origin": "https://portal.yourcompany.example", "groupId": 7, "bookmarkId": 3 }'
| Field | |
|---|---|
reportId | One of the client's reports |
subject | { "userId": 456 } or { "emailAddress": "..." }: one of the members or guests the client may act as |
origin | The site the page runs on: one of the client's allowed sites, exactly as the browser writes it (https://host[:port]) |
groupId | Optional: one of the client's row access groups. Datasets with row access on then show that group's rows instead of the subject's |
bookmarkId | Optional: a bookmark of the report to open at |
lifetimeSeconds | Optional: 60 to 900 (the default is 15 minutes) |
The answer:
{ "token": "...", "expiresAt": 1793000000, "workspaceId": 12, "reportId": 123, "embedUrl": "https://InsightFastPass.com/embed/app" }
A refusal is 403 with a code: clientDisabled, planRefused, reportNotAllowed, subjectNotAllowed, originNotAllowed or groupNotAllowed. The subject's own access to the report is checked when the frame reads it: a subject who has lost access sees the report as unavailable, and your page is told (sessionEnded with forbidden).
Make this call from your server, behind your own sign-in, and decide there which subject and group your user gets. Never put the client secret, a private key or an access token in a page.
3. Show it on your page#
<div id="report"></div>
<script src="https://InsightFastPass.com/embed.js"></script>
<script>
InsightFastPass.embed({
container: '#report',
// Your server's endpoint that does steps 1 and 2 and answers { token }.
token: () => fetch('/api/report-token', { method: 'POST' }).then(r => r.json()).then(r => r.token),
theme: 'light',
autoHeight: true,
onLoad: e => console.log('Showing', e.reportName),
onSessionEnded: reason => console.log('Ended:', reason),
onError: e => console.warn(e.code, e.message)
});
</script>
embed.js makes the frame at /embed/app, waits for it to be ready, calls your token() and hands the frame the token. About two minutes before the token ends the frame asks for another, and embed.js calls token() again, so the report stays open for as long as the page does. The frame checks that the token names the site it was sent from, and from then on talks only to that site.
The host script, embed.js#
https://InsightFastPass.com/embed.js is a small plain script (no framework) that any site may load. It is optional for public and signed-in embeds, and the easy way to do embedding through an app.
InsightFastPass.embed(options) returns { iframe, setBookmark(bookmarkId), print(), destroy() }. InsightFastPass.embedVersion is the script's version.
| Option | |
|---|---|
container | The element to put the frame in, or a selector |
token | Through an app: a function that returns (a promise of) an embed token. Called once at the start and again whenever the frame asks |
url | Public or signed in, instead of token: the embed address from the snippet (/embed/r/<code> or /embed/w/<workspace>/<report>) |
theme | light or dark; left out, the frame follows the visitor's system setting |
toolbar | false hides the frame's toolbar |
bookmarkId | Public or signed in: a bookmark to open at (through an app it is in the token) |
autoHeight | true sizes the frame to the report's content |
height, title, loading | The frame's starting height (600px), its accessible title (Report) and loading (lazy) |
onLoad, onSessionEnded, onError, onHeight | Called with what the frame reports (below) |
Without the script#
The frame and the page talk with postMessage. Every message is an object { ifp: 1, type, ... }.
From the frame to your page:
type | When | Fields |
|---|---|---|
ready | The frame is listening | mode: public, signedIn or app |
loaded | The report is on screen | reportId, reportName, kind (dashboard or printable) |
height | The report's content height changed | px |
tokenExpiring | Through an app: two minutes before the token ends, then every 30 seconds until a new one arrives | expiresAt (seconds since 1970) |
sessionEnded | The token ended with none to replace it, or access was taken away | reason: expired, revoked or forbidden |
error | Something failed | code, message |
From your page to the frame:
type | Fields | |
|---|---|---|
setToken | token | Through an app: the first one opens the report; later ones replace the token before it ends |
setBookmark | bookmarkId | Opens a bookmark of the report |
print | Prints, as the toolbar's Print does |
By hand, through an app:
const app = 'https://InsightFastPass.com';
const frame = document.querySelector('#report-frame'); // src = app + '/embed/app'
async function sendToken() {
const { token } = await fetch('/api/report-token', { method: 'POST' }).then(r => r.json());
frame.contentWindow.postMessage({ ifp: 1, type: 'setToken', token }, app);
}
window.addEventListener('message', e => {
if (e.origin !== app || e.source !== frame.contentWindow || e.data?.ifp !== 1) return;
if (e.data.type === 'ready' || e.data.type === 'tokenExpiring') sendToken();
});
Always post with your app's origin as the target (never '*'), and ignore messages that don't come from that origin and that frame. The frame does the same: it sends nothing but ready until it knows which site it is on, and from then on talks only to that site.
Address options#
These work on the /embed/r/... and /embed/w/... addresses (and embed.js sets them from its options):
| Parameter | |
|---|---|
?bookmark=<id> | Open at a bookmark. A bookmark since deleted opens the report as saved, with a note |
?theme=light or ?theme=dark | The frame's colours |
?toolbar=0 | No toolbar: the report alone |
?via=<tag> | Public only: a tracked link's tag |
What a viewer sees#
- The report in Dash view, filling the frame. A thin toolbar above it has the report's name, its bookmarks, Print, and in a signed-in embed the person's name with Not you?. A small Insight FastPass mark sits in the bottom-right corner.
- While it opens: "Opening the report…"; through an app, before the first token: "Waiting for the page…".
- "This report isn't available" when the report is private, gone or not theirs to see; "Your session ended" when the sign-in or the token ran out (with Sign in again in a signed-in embed); "Too many tries from this network" when the site is being rate limited.
- Nothing they do is saved: no favourites, no last-opened, no bookmarks written.
Troubleshooting#
- Third-party cookies. Embeds don't use cookies, so blocking third-party cookies, private windows and Safari's tracking prevention don't affect them.
- "Your browser blocked the sign-in window." The signed-in embed's sign-in opens a popup when Sign in is clicked. Allow popups for the site, and check that the
<iframe>hasallow-popups allow-popups-to-escape-sandboxin itssandboxattribute. - "This report can't be shown on this site." The report's allowed sites (or, through an app, the token's
origin) don't include the page's origin. Origins are exact:https://www.example.comandhttps://example.comare different sites, and so are different ports. - "This site can't be checked." The report lists allowed sites and the browser didn't say which site the page is on (Firefox with a strict referrer policy). Add
referrerpolicy="strict-origin-when-cross-origin"to the<iframe>, or useembed.js. - The frame stays on "Waiting for the page…". Through an app, the page never sent a token, or sent one for another site: check
onError, and thatoriginin your CreateEmbedToken call matcheslocation.originof the page exactly. 403 originNotAllowed/subjectNotAllowed/reportNotAllowed/groupNotAllowed. The request named something outside the client's lists. An admin can add it on the client's page under Security.invalid_client. The client id, secret or assertion is wrong, the secret has passed its end date, or the assertion'saud,exporjtiis off (ajtican be used only once).- The report goes blank after a while. Your
token()endpoint failed when the frame asked for a new token:onErrorreportstokenFailed, andonSessionEndedfollows when the token ends. - The frame refuses to load at all. The page must be on
https(orhttp://localhostwhile testing), and nothing in your own site's Content Security Policy may blockframe-src https://InsightFastPass.com.