Install Flawsnap on any HTML website

Steps

1. 1

   Create a project and copy the snippet

   In Flawsnap, create a project for the site. The Install on your website panel shows the Website snippet with your project key.

2. 2

   List your domains

   Open the project’s Security section and add each host the site runs on under Allowed domains, one per line, including localhost:PORT for local testing.

3. 3

   Paste the tag into the head

   Add the snippet inside <head> on every page, or once in the shared header or layout template your pages use.

4. 4

   Deploy and open the site

   Upload or deploy the change and open the site in a browser.

5. 5

   Confirm Flawsnap sees it

   Back in Flawsnap, the install panel changes from Waiting for the widget to load on your site… to Widget detected with your domain.

The tag and where it goes

In the <head> the widget starts before your own scripts run, so it records console messages and fetch/XHR calls from page load. async means it downloads without blocking the page. Placing it just before </body> also works, but anything logged before it loads will not be in reports.

Every page needs the tag. A site generator, PHP include or server template with a shared head means you add it once.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>My site</title>
    <script src="https://backend.flawsnap.com/widget.js" data-key="pk_…" async></script>
  </head>
  <body>
    …
  </body>
</html>

Attributes you can set on the tag

Label, position and colour set in the Flawsnap project settings override these attributes.

Testing on your own machine

Opening the file straight from disk (file://) will not work: the browser has no real origin to send, so Flawsnap cannot match it to an allowed domain. Serve the folder instead and allow that address with its port:

# from the folder with index.html
python3 -m http.server 8000
# then allow localhost:8000 in the project's Allowed domains

localhost:8000 and localhost:3000 are different entries: the port must match.

Adding details about the visitor

If your site knows who is signed in, set it before the tag loads. The metadata object is attached to every report, which helps when one account sees a bug and another does not.

• Later on the page you can call Flawsnap.identify({ name, email }) and Flawsnap.setMetadata({...}) once the widget has loaded.
• identify fills in the report form only. It is never sent to Insights.

<script>
  window.FlawsnapConfig = {
    reporter: { name: 'Sam Lee', email: '[email protected]' },
    metadata: { account: 'acme', release: '2026.11.1' }
  };
</script>

Troubleshooting

• [flawsnap] missing project key: the data-key attribute is missing or misspelled.
• [flawsnap] widget disabled:: the domain is not allowed, or the key was regenerated and the page still has the old one.
• A Content Security Policy blocks the script: allow https://backend.flawsnap.com in script-src and connect-src.
• Team sign-in fails to connect: your Cross-Origin-Opener-Policy header must be same-origin-allow-popups or unsafe-none, not same-origin.

Questions

Do I need a build step or npm package?

No. The widget is a hosted script. Any site that serves HTML, static or server-rendered, can use it.

Can someone copy my snippet onto their own site?

The key only works from the domains on your allowed list. On any other site the widget refuses to start.

Does it slow the page down?

The tag is async, so the page does not wait for it. The parts for Insights and recordings only load for projects that use them.

Related

• Install Flawsnap with Google Tag Manager
• Console and network logs, attached to every report
• Device and browser details, filled in for you
• What is visual bug reporting?
• Docs