Embed a report on your site
Put a published report or one chart on your own website with an iframe or the halo-report element, and list the sites it may appear on.
An embed shows a published report on another website. It needs no sign-in, and you can use it for a whole report or one chart. By the end of this page, your report will be on your site.
Pick a method
| Iframe | <halo-report> element | Signed embed | |
|---|---|---|---|
| Good for | A CMS or any page that takes HTML | Your own pages, with a line of script | Dashboards inside your own product |
| Sizes to its content | No, you set the height | Yes | Yes, with the element |
| Your page can set filters and hear clicks | No | Yes | Yes, with the element |
| Readers see rows from datasets with row policies | No | No | Yes, by the token's attributes |
| Needs your server | No | No | Yes |
Use the first two for public numbers. If each reader should see their own rows, read Signed embeds.
Embed a report
You need edit access to the report and the Embed reports permission.
Publish the report. See Drafts, versions and publishing.
Choose Share, and find Embed.
Under Sites it may be embedded on, add your site, then Add.
Give it an optional Name and Expiry, and choose Make link. New embed link adds another.
Pick
<halo-report>or iframe on the link's row, and copy the snippet into your page.
Try the options here:
The builder's addresses are samples. Your report's own are in its Share dialog.
The iframe
<iframe src="https://{org}.usehalo.net/embed/hle_…" title="Revenue report" width="100%" height="640" style="border: 0" loading="lazy" allow="fullscreen"></iframe>It's plain HTML, so it works anywhere that takes it. Set the height yourself, as the frame doesn't grow with the report. To start in another mode, add ?theme=dark or ?theme=system to the address. Embeds start light.
The <halo-report> element
<script type="module" src="https://cdn.usehalo.net/halo-report.js"></script>
<halo-report src="https://{org}.usehalo.net/embed/hle_…"></halo-report>Include the script once per page. The element grows to the report's height unless your page sets one. It also has attributes for theme and starting filters, methods to set filters, and events for clicks and errors. All of it is in The <halo-report> element.
Allowed sites
Each report has one list of sites it may be framed on, for all its embed links and signed embeds. Your organization's own live websites in Halo CMS and its Halo address may always frame its reports. With an empty list, nowhere else may, so an embed link on another site shows nothing until you add that site.
| Write | Allows |
|---|---|
example.com | That site, over https |
*.example.com | Its subdomains, not example.com itself. List both if you need both |
localhost:3000 | That port on your own machine, for trying it out |
localhost | Any port on your own machine |
You can paste a full address, and Halo keeps just the site. Ports are only for localhost, and IP addresses aren't accepted. A report can list up to 50 sites.
A browser enforces the list, through the frame-ancestors security header. On a site that isn't listed, the browser refuses to draw the frame.
Embed one chart
To show one chart, name the element:
<halo-report src="https://{org}.usehalo.net/embed/hle_…" element="revenue-by-month"></halo-report>In an iframe, add ?element=revenue-by-month to the address. If the element is no longer in the published report, the embed says so, and your page hears element_not_found.
What embed readers get
The same as a public link: only the published version, your brand, and only the datasets and fields the report uses. An unlocked report filter doesn't limit what an embed can ask for. Locked filters do, and so do row policies on a signed embed.
A snapshot or live data, as the report is set. See Public links and snapshots.
No rows from a dataset with row policies. For those, use a signed embed.
A small "Powered by Halo" badge, unless your plan removes it. A one-chart embed shows it too.
If it doesn't show
| You see | Why |
|---|---|
A refused or empty frame, and a console message about frame-ancestors | The site isn't on the report's list, or isn't https |
| "This report can't be shown here" | A signed embed on a site that isn't on the list |
| "This report isn't published yet" | Publish it. Links work from then on |
| "Report not found" | The link was turned off, its address changed, or the report is in the Trash |
| Charts with no rows | A dataset has row policies. Use a signed embed |
This report can't be shown here, with a sentence saying the organization hasn't allowed it on this website and can add the site to the report's allowed domains