Add a feedback widget to a Ghost blog

Code injection or a theme edit?

Ghost has a code injection area in the site settings, with separate fields for the site header and the site footer. The footer field is where the widget goes. Anything you paste there is added to every page, so the floating Feedback button appears on posts, the homepage and the archive pages.

Code injection is static HTML. It does not run Handlebars, the template language Ghost themes use, so it cannot read the signed-in member or insert their details. If you want the widget to know who is reading, you need to edit the theme, which requires a self-hosted Ghost site or a theme you control. The widget works without that edit, so start with code injection.

Add the widget to the site footer

Open the Ghost admin settings, find code injection, and paste the footer snippet into the site footer field:

<script src="https://escutaproduto.com/widget.js" data-key="pk_your_product_key" defer></script>

Save, then open a published post in a private window. The Feedback button should appear in the corner. Ghost's preview is useful for layout, but test the published address to confirm the script runs for real readers.

Why code injection can't see the signed-in member

Ghost sends member data to templates, not to the footer field. A snippet that says "identify this member" would have to know the member's email at render time, and static code injection cannot do that. The result would be a fixed value, or nothing at all.

The fix is a theme template. Ghost exposes the current member to Handlebars as the member object, and you can check for a signed-in member with a conditional. Add a block like this to a template your theme renders on every page, such as the default template:

{{#if @member}}
<script>
  window.EscutaProduto = window.EscutaProduto || { q: [] };
  (window.EscutaProduto.q ||= []).push(["identify", [{
    email: "{{@member.email}}"
  }]]);
</script>
{{/if}}

This sample passes only the email. Ghost escapes its output, so a name with quotation marks could appear with escaped characters in the form. The email is the field that matters most, because it hides the email box for the reader. Keep the identify block above the widget script, or rely on the queue pattern, which works in either order.

If you cannot edit the theme, skip identify. Readers can still send feedback with an email field, which is enough for most blogs.

Add a prompt to a single post

A floating button is good for general feedback. A post that teaches a technique might need a more specific prompt, such as a question about a code sample. The floating button stays on, and you add a button inside the post.

In the post editor, add an HTML card where you want the prompt and paste:

<button type="button" data-escuta-open="bug">Report a problem with this post</button>

The attribute opens the form with the bug type already selected. The page URL is saved with the message, so you can see exactly which post the reader meant. Use the same approach for ideas, with data-escuta-open="idea", on posts that announce or describe an upcoming feature.

If you want the floating button off everywhere and only the in-post prompts visible, add data-trigger="none" to the footer script. Test a post afterward, because that choice removes the button from every page.

Check a live post as a reader and as a member

Open a published post in a private window while logged out. Send a message and confirm it arrives. Then sign in as a test member and open the same post. If your theme includes the identify block, the email field should be hidden. If the field still shows, check that the identify block is present in the rendered page source for members.

Look at the item in your inbox afterward. The page URL should match the post, which is the proof that the widget is on the right page.

Reader feedback in Escuta Produto

Reader messages land in the inbox of the product you created for the blog. Filter by type to separate bugs in a tutorial from ideas for new posts and praise from readers. Use statuses to show what you have planned, so you can reply to readers once the thing they asked for ships.

Internal notes are where you record the decision, such as a post you updated because of a bug report. The 30-day chart shows whether a spike of messages follows a new post, which helps you judge what readers care about.

Troubleshooting a silent install

When you finish the install and nothing arrives, go through these checks in order.

Start with the footer field. If the script sits in the site header field instead, it still loads, but a mistake in the other field can hide the button on posts. Confirm the snippet is in the site footer, save, and reload a post in a private window.

Next, check the post you are testing. A post with its own code injection that changes the page structure can hide a button placed inside the post body. Test on a plain published post first, then add the in-post prompt once the floating button works.

Then check the member identify block. If members see the email field after signing in, the template conditional is probably not rendering for them. View the page source while logged in as a member and look for the identify call. If it is missing, the edit is in the wrong template file, or the template does not render on that page.

Last, check allowed origins. A feedback request from a custom domain that is not listed will fail with a 403 response, even though the button is visible. Add the live address with https, then test again.

Related

• Full widget options are in the widget docs.
• The link-only option, which needs no theme access, is in the hosted page docs.
• For a similar footer-injection install, read Add a feedback widget to a Squarespace site.
• For the difference between a message and a request, read Bug report vs feature request.