Docs/Guides
Add HeedPost to your product.
Let customers share feedback, follow the roadmap and read updates without leaving the page they were on.
Portal or widget?
The public boarda full destinationA shareable board with its own address, navigation and search. Customers can bookmark it and you can link to it from anywhere.
The widgetinside your productA focused panel opened from your app. Customers stay on the page they were on, and if they're signed in, they don't have to say who they are.
Most teams use both: the board for the world, the widget for the people already in the product.
Install the script
Copy the snippet from Settings › Widget and place it once, before the closing body tag, on the pages where HeedPost can open.
<script src="https://acme.heedpost.com/widget.js"
data-board="feedback"
async></script>The address is your own workspace's. The script is served by your workspace and carries its name and colour, so there's no shared script host to load it from. Copy it from your settings instead of typing it.
The launcher lives in a Shadow DOM, so your page's CSS cannot reach it, and the panel is an iframe, so ours cannot reach your page.
Attributes
data-boardthe boardThe address of the board the panel opens on, like
feedback.data-identityoptionalA token your server signed for the customer who is logged in. See identifying customers.
data-localeoptionalThe language your page is written in, like
de. Without it the widget follows the reader. The tags.data-badgeoptionallabeladds a pill beside the launcher saying how many releases are new to the reader, like “2 new releases”. Without it, a dot on the launcher says the same.
<script src="https://acme.heedpost.com/widget.js"
data-board="feedback"
data-identity="<token your server signed>"
data-locale="de"
data-badge="label"
async></script>What is in the panel
The panel opens on the board named by data-board, with Roadmap and Changelog as tabs beside it. A dot on the launcher marks a release the reader has not seen, and opening the Changelog tab clears it.
The launcher is always shown, and no attribute hides it. Opening the panel from your own button adds a second way in. It doesn't replace the launcher.
The JavaScript API
Four functions on window.Heedpost.
window.Heedpost.open(); // open the panel window.Heedpost.close(); // close it; focus returns to the launcher window.Heedpost.identify(token); // sign a customer in, or out with null window.Heedpost.identify(() => fetchToken()); // or hand it a function window.Heedpost.locale("ar"); // a page that changes language without a reload
A Give feedback item in your own menu can open the panel without anybody hunting for the launcher:
document.querySelector("#feedback").addEventListener("click", () => {
window.Heedpost?.open();
});The script is async, so window.Heedpost is not there on the first paint. Guard the call the way the snippet does. Nothing queues a call made too early, and a handler wired at the top of your own bundle will run before ours has.
Identify signed-in customers
Pass a verified identity from your server, so posts and comments arrive with the customer's name. It's the same token single sign-on uses, signed the same way, and its claims are here. It needs Plus or Pro. Never sign it in the browser.
In the attribute
The two minutes start when you render the page, and the widget uses the token when someone first presses the launcher. A reader who opens it later, or a page cached for ten minutes, gets the public board, and your console notes that the token was too old. So the attribute suits a page someone acts on straight away.
As a function
Otherwise, give window.Heedpost.identify a function that fetches a fresh token from your own server, or returns null for nobody. The widget calls it only when it needs a token: on the first press, after locale(), and before its own session ends. The reader stays signed in however long the page is open.
<script src="https://acme.heedpost.com/widget.js"
data-board="feedback"
onload="Heedpost.identify(() =>
fetch('/heedpost-token').then((answer) => answer.text()))"
async></script>After your app signs somebody in
A single-page app that signs someone in without reloading calls window.Heedpost.identify(token) with a fresh token, and identify(null) signs them out of the panel. The panel's own session lasts twelve hours.
A token we will not accept is not an error your users see. The panel opens as the public board and one line in the browser console says why, which is where the developer who wrote the tag is looking.
Languages
The widget follows the reader's browser, then your workspace's default language. Name your page's language with data-locale, or call window.Heedpost.locale(tag) when your page changes language without a navigation. Changing it while the panel is open draws the panel again in the new language, from its first page.
en ar bn de es fr he hi it ja ko ms nl pt-BR ru sw ta tr ur zh-CN zh-Latn-pinyin
zh-Latn-pinyin is Chinese in Hanyu Pinyin. A regional tag such as de-AT is read as the nearest of these, one we do not speak is ignored, and locale(null) hands the choice back to the browser. Arabic, Hebrew and Urdu draw right to left.
Test it
- Load a page with the script installed.
- Open the widget from the launcher, and from your own button if you added one.
- Submit a private test post and check it landed on the right board.
- Check keyboard focus, closing with Escape, and the layout on a phone.
Troubleshooting
Nothing opensCheck the tag loads from your workspace's own address and appears once. A call to
open()before the script has loaded does nothing: guard it withwindow.Heedpost?.open().The wrong boarddata-boardtakes the board's address, not its name. Check the board is one the reader may see.Signed outA token in the attribute has to be used within two minutes of the page loading, and the console says when one was too old. Give
identify()a function instead.Styles clashThey cannot: the launcher is in a Shadow DOM and the panel is an iframe. If something looks wrong, it is worth a message to us.