Install Flawsnap on a WordPress site

Steps

1. 1

   Copy the snippet

   In Flawsnap, open Projects, pick the project for this site and copy the Website snippet from Install on your website.

2. 2

   Allow your domain

   In the same project, open Security and add your site's domain under Allowed domains, one per line. Add www. as its own line if visitors use it.

3. 3

   Add the snippet to the head

   Paste the snippet into the header box of a header-and-footer code plugin, or add it from your child theme with a wp_head hook (code below). Save.

4. 4

   Clear your caches

   If you run a page cache or a CDN, purge it so visitors get pages that include the new tag.

5. 5

   Check it loaded

   Open your site in a private window. The button should appear in the corner, and the project page in Flawsnap should say Widget detected on your domain.

Where the snippet goes in WordPress

The widget is a single script tag. It belongs in your theme's <head>, so it starts early enough to capture console messages and API calls from page load. async stops it from holding up the page.

Never edit WordPress core files or your parent theme directly. Core updates replace core files, and theme updates replace the parent theme's files, so your tag would vanish without warning. You have two safe options.

• A header code plugin. Plugins that add code to every page's head (WPCode is a common one) give you a box to paste into. This survives theme changes, and nobody needs to touch PHP.
• A child theme. If you already run a child theme, a wp_head hook in its functions.php keeps the tag in version control with the rest of your theme code.

<script src="https://backend.flawsnap.com/widget.js" data-key="pk_…" async></script>

The child theme version

Add this to your child theme’s functions.php. Priority 1 prints it near the top of the head.

add_action( 'wp_head', function () {
	echo '<script src="https://backend.flawsnap.com/widget.js" data-key="pk_…" async></script>' . "\n";
}, 1 );

Some optimisation plugins combine, defer or "delay" JavaScript until the visitor interacts. If the button only appears after a click or scroll, exclude widget.js from that setting.

Prefill the name and email of logged-in users

Anyone can report without an account; the form simply has optional name and email fields. If your testers or members log in to WordPress, you can fill those in for them. Set window.FlawsnapConfig.reporter before the widget loads. Priority 0 makes this run before the snippet at priority 1.

add_action( 'wp_head', function () {
	if ( ! is_user_logged_in() ) {
		return;
	}
	$user     = wp_get_current_user();
	$reporter = array(
		'name'  => $user->display_name,
		'email' => $user->user_email,
	);
	printf(
		'<script>window.FlawsnapConfig = Object.assign(window.FlawsnapConfig || {}, { reporter: %s });</script>' . "\n",
		wp_json_encode( $reporter )
	);
}, 0 );

Most page caches skip logged-in users. Check that yours does, or one person's name could be cached into pages other people see.

Domains to list for a WordPress site

• example.com and www.example.com are separate hosts. List both if both load.
• A staging copy on a subdomain: add staging.example.com, or *.example.com to cover every subdomain (the wildcard does not cover the apex).
• A local install such as localhost:8080: include the port. localhost sites work for testing, and team sign-in works there too.
• Multisite with one widget per site: give each site its own Flawsnap project and key, so reports land on the right board.

If the button does not appear

• Open the browser console. [flawsnap] widget disabled: followed by a reason usually means the domain is missing from Allowed domains, or the key is wrong.
• View the page source and search for widget.js. If it is missing, the plugin is off, the hook is in the wrong theme, or a cache is serving old pages.
• widget.js is on this page twice means both a plugin and your theme add it. That is harmless (the second copy is ignored), but remove one.
• Check the project settings in Flawsnap: an admin can turn off Show on website (under Report a bug button), which hides it even when the script loads.
• With a strict Content Security Policy from a security plugin or your server, allow https://backend.flawsnap.com in script-src and connect-src.

Questions

Does it work on WordPress.com as well as self-hosted WordPress?

It needs a way to add a script tag to the head. On WordPress.com that means a plan that allows plugins or theme code. On a self-hosted site you always have that option.

Will a theme update remove the widget?

Not if you use a header code plugin or a child theme. It only disappears if the tag was pasted into the parent theme, which is why you should not put it there.

Can I show the button only to my team?

Yes. Turn off Show on website (under Report a bug button) in the project settings, then open the form from your own link or admin bar item with window.Flawsnap?.open(). The script still has to be on the page.

Related

• Install Flawsnap on any HTML website
• Install Flawsnap with Google Tag Manager
• Client feedback for web agencies
• Screenshot annotation for bug reports
• How to collect client feedback on a website without the chaos