---
title: "The site widget"
description: "How to add a \"Report a bug\" button to your own website, so its users can send a screen recording or the last two minutes of the page to your Faylee workspace."
canonical: https://faylee.app/docs/support/widget
---

# The site widget

The site widget is a "Report a bug" button you add to your own website with one script tag. People using your site press it to send you a screen recording, or the last two minutes of the page, with the console, network requests and their steps. They don't need Faylee, an account or the extension. Reports land in your workspace like any other recording.

## Adding a site

Only workspace admins can add sites.

1. Open **Settings**, then **Sites**.
2. Under **Capture widget**, type the **Domain** your site runs on, such as `app.example.com`.
3. Choose a folder under **File reports in**, if you want reports filed in one. This shows when your workspace has folders.
4. Press **Add site**.

The site's card then shows the two steps to finish setup: prove you own the domain, then add the script to your pages. It shows as **Not verified** until step one is done.

## Letting your coding agent do it

On a site that isn't verified yet, press **Copy setup prompt** and paste it into Claude Code, Codex or Cursor in your website's codebase. The prompt holds your token and your snippet, so the agent can add the verification file and the script in one go. Deploy, then press **Verify** on the site's card.

## Verifying the domain

Faylee accepts reports only from domains you have verified, so nobody else can send reports into your workspace from their site.

1. On the site's card, press **Copy token**.
2. Publish a text file at `/.well-known/faylee-verification.txt` on your domain, containing the token. For the domain `app.example.com`, the file must be at `https://app.example.com/.well-known/faylee-verification.txt`.
3. Press **Verify** on the site's card.

Faylee fetches the file over HTTPS and does not follow redirects, so the file must be served at that exact address. Once verified, the card shows **Verified**.

The token is public by design. It only proves you control the domain, and it can't be used to read or send anything.

## Adding the script

The site's card shows your snippet, with your site's key filled in, from the moment you add the site. Press **Copy snippet** and add it to every page that should show the button, before the closing `</body>` tag. You can add it before verifying: the button accepts reports once the domain is verified.

```html
<script src="https://app.faylee.app/widget.js" data-site="site_..." async></script>
```

`data-site` is your site's key. The example shows `site_...` where your copied snippet has the real key.

The widget draws its button and panel in its own isolated part of the page, so your site's styles don't affect it and it doesn't affect them.

Reports are accepted from the verified domain and its subdomains, over HTTPS. A page on another domain that loads the same snippet can't send reports. The widget uploads through a hidden frame on Faylee's address, which only your verified domain can load.

### If your site has a Content Security Policy

Allow `https://app.faylee.app` in `script-src`, `connect-src` and `frame-src`. The widget loads from there, talks to it, and uploads through its frame.

## Making it look like your site

Under **Make it look like your site** on the site's card, choose how the widget appears and see a preview as you change it:

- **Style**: a **Floating button** in a corner, a **Side tab** on the edge of the page, or **Your own button**.
- **Side**, and how far to move it **Up** and **In from the side**, so it stays clear of your own buttons and inputs.
- **Label**, the button's text.
- **Theme**: follow the visitor's light or dark setting, or always light or dark.
- **Accent**, **Background** and **Text** colours. **Reset** goes back to Faylee's.

Press **Save look**. The widget picks it up the next time a page loads, so your snippet and your site's code stay the same.

### Using your own button

With **Your own button**, the widget shows no button of its own. Open it from any button in your app, styled like the rest of it:

```html
<button type="button" onclick="window.faylee?.open()">Report a bug</button>
```

### Setting it in code instead

Attributes on the script tag win over what you saved: `data-launcher` (`button`, `tab` or `none`), `data-position` (`left` or `right`), `data-theme` (`auto`, `light` or `dark`) and `data-label`. The colours can also be set from your own CSS, on the widget's element:

```css
#faylee-widget {
  --faylee-accent: #2563eb;
  --faylee-background: #0b0b0c;
  --faylee-foreground: #f5f5f5;
}
```

## What your users see

The button reads **Report a bug**, unless you chose another label. Pressing it opens a panel that says the report goes to your workspace, with the page's console and network from the last few minutes, and that passwords and tokens are hidden. The panel asks for:

- **Your name** and **Your email**, both optional.
- **What went wrong?**

Then it offers two ways to send:

- **Record screen** starts a screen recording. The browser asks which screen, window or tab to share, and suggests the current tab. While recording, the panel shows **Stop and send**, which stops the recording and sends it.
- **Send what just happened** sends what happened on the page in the last two minutes, without a video.

After sending, the panel says the report was sent to your workspace. If it fails, it shows why and offers **Try again**.

## What it records

The widget starts watching the page as soon as it loads, the way the extension's instant replay does. It keeps the last two minutes in memory on the page. Nothing leaves the page until the person sends a report.

A report contains:

- The console output and uncaught errors.
- The requests the page made with `fetch` and `XMLHttpRequest`, with their bodies. The widget's own requests to Faylee are left out.
- The clicks, typing and page changes, as steps.
- The page itself, so it can be replayed, if the site records the page. See below.
- The browser, system, window size and other details of the device.
- For **Record screen**, the video, without sound.

A recording sent with **Record screen** opens in the viewer as a video. A report sent with **Send what just happened** has no video. It replays the page itself if the site records the page, and otherwise plays as a list of steps beside the devtools.

### Recording the page

Each site's card on **Settings → Sites** has **Record the page for instant replay** under **Choose what reports include**. It is on for new sites.

- **On:** the widget also records the page itself, the way the extension's instant replay does. A report of what just happened opens in the **Page** view, where you watch what was on screen, with the clicks, scrolling and typing, next to the console and network. Password fields, fields with a credit card, one-time code or password `autocomplete` value, and anything marked `data-faylee-mask` or `faylee-mask` are hidden in the replay. The widget never records itself. When a report is sent, the widget also draws a picture of the page for the report's card, with the same parts left out. It is redrawn from the page, so canvases and images from servers that refuse other sites may come out blank. The recorder is a second script, about 23 kB compressed, which the widget loads from Faylee when the page opens.
- **Off:** the widget doesn't load the recorder. A report of what just happened carries the steps as a list, with the console and network, but you don't see the page itself, and its card has no picture.

Screen recordings work either way. If your workspace turns off **Allow instant replay** on **Settings → Privacy**, no site records the page, whatever its card says.

:::note
The widget runs inside your page, so it sees less than the extension. It doesn't capture requests the page didn't make with `fetch` or `XMLHttpRequest`, such as scripts, images and stylesheets.
:::

## Blurring

While a screen recording runs, Faylee blurs these on screen, so they are blurred in the video itself:

- Password fields.
- Fields with a credit card, one-time code or password `autocomplete` value.
- Anything your site marked with the `data-faylee-mask` attribute or the `faylee-mask` class, and everything inside it.

The person recording can hide more. **Blur part of the page** in the panel lets them click any element on the page to blur it, and click a blurred element to show it again. **Done blurring** ends picking. Clicks made while picking are not passed to your page and are not recorded as steps.

See [Privacy and redaction](https://faylee.app/docs/workspace/privacy#masking-parts-of-your-page) for marking elements on your site.

## Privacy rules

Before a report is uploaded, the widget hides secrets in it the same way the extension does: authorization headers, cookies, tokens and passwords in headers, bodies and addresses. It also applies your workspace's privacy rules, so any headers and fields your admins added are hidden too. See [Privacy and redaction](https://faylee.app/docs/workspace/privacy.md).

## Where reports go

Each report is filed under the member who added the site, in the site's folder when it has one, with the reporter's name and email when they gave them. The site's card in Settings shows how many reports came from it.

To stop accepting reports, press **Remove** on the site's card. Its widget stops accepting reports, and reports already sent stay in your workspace. A site also stops accepting reports when the member who added it leaves the workspace.

## Related

- [Recording links](https://faylee.app/docs/support/recording-links.md)
- [Privacy and redaction](https://faylee.app/docs/workspace/privacy.md)
- [Instant replay](https://faylee.app/docs/capture/instant-replay.md)