Back to Insight FastPass

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.

12 min read

The three ways to embed#

WayWho sees the reportHow they are identifiedWho sets it up
PublicAnyone who can see the page it is onNobody: it is the report's public link, in a frameSomeone with Manager access to the report (the report must be public)
Signed inPeople who can already open the report: members with access, and guests it was shared withThey sign in to Insight FastPass in a small window; the frame then shows the report as themSomeone with Manager access to the report turns on embedding for it
Through an appYour application's own usersYour 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 guestThe 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.

  1. Make the report public (the Share dialog's Public link section, Anyone with the link can view).
  2. 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.
  3. 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.

  1. 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.
  2. Copy the snippet: the same <iframe> as above, with src="https://InsightFastPass.com/embed/w/<workspace id>/<report id>".

What a viewer sees:

  1. The frame says Sign in to view this report with a Sign in button.
  2. 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.
  3. 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.
  4. 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
reportIdOne of the client's reports
subject{ "userId": 456 } or { "emailAddress": "..." }: one of the members or guests the client may act as
originThe site the page runs on: one of the client's allowed sites, exactly as the browser writes it (https://host[:port])
groupIdOptional: one of the client's row access groups. Datasets with row access on then show that group's rows instead of the subject's
bookmarkIdOptional: a bookmark of the report to open at
lifetimeSecondsOptional: 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
containerThe element to put the frame in, or a selector
tokenThrough an app: a function that returns (a promise of) an embed token. Called once at the start and again whenever the frame asks
urlPublic or signed in, instead of token: the embed address from the snippet (/embed/r/<code> or /embed/w/<workspace>/<report>)
themelight or dark; left out, the frame follows the visitor's system setting
toolbarfalse hides the frame's toolbar
bookmarkIdPublic or signed in: a bookmark to open at (through an app it is in the token)
autoHeighttrue sizes the frame to the report's content
height, title, loadingThe frame's starting height (600px), its accessible title (Report) and loading (lazy)
onLoad, onSessionEnded, onError, onHeightCalled 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:

typeWhenFields
readyThe frame is listeningmode: public, signedIn or app
loadedThe report is on screenreportId, reportName, kind (dashboard or printable)
heightThe report's content height changedpx
tokenExpiringThrough an app: two minutes before the token ends, then every 30 seconds until a new one arrivesexpiresAt (seconds since 1970)
sessionEndedThe token ended with none to replace it, or access was taken awayreason: expired, revoked or forbidden
errorSomething failedcode, message

From your page to the frame:

typeFields
setTokentokenThrough an app: the first one opens the report; later ones replace the token before it ends
setBookmarkbookmarkIdOpens a bookmark of the report
printPrints, 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=darkThe frame's colours
?toolbar=0No 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> has allow-popups allow-popups-to-escape-sandbox in its sandbox attribute.
  • "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.com and https://example.com are 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 use embed.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 that origin in your CreateEmbedToken call matches location.origin of 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's aud, exp or jti is off (a jti can be used only once).
  • The report goes blank after a while. Your token() endpoint failed when the frame asked for a new token: onError reports tokenFailed, and onSessionEnded follows when the token ends.
  • The frame refuses to load at all. The page must be on https (or http://localhost while testing), and nothing in your own site's Content Security Policy may block frame-src https://InsightFastPass.com.