Troubleshooting

Most install issues come down to one of four things: the script never loaded, the project key is wrong, your Content Security Policy blocked the request, or — with the programmatic embed — init() was never called. Work through the sections below in order; the browser’s developer console is your fastest diagnostic.

Open the console first

Open your browser’s developer tools (F12 or right-click → Inspect → Console) before reloading the page. Patchrooms reports configuration problems there, so the console almost always tells you what went wrong.

The widget does not appear

Check the console for an unknown-key error

When you embed the per-project loader, the server looks up your project key and inlines its configuration. If the key doesn’t resolve to a real project, the loader does not throw — it logs an error and does nothing:

[Patchrooms] unknown project key: pr_xxx

If you see this message, the project key in your script URL is wrong. See Wrong project key below.

Confirm the script actually loaded

1. Open the Network tab in developer tools and reload the page.
2. Look for a request to room.patchrooms.com:
   • With the one-line loader, that’s …/v1/patchrooms/pr_xxx.js.
   • With the programmatic embed, it’s …/v1/patchrooms.js.
3. Check the status:
   • No request at all → the <script> tag isn’t on the page, or something blocked it. See Script blocked / CSP.
   • A blocked or failed request → almost always Content Security Policy. See Script blocked / CSP.
   • 200 OK → the bundle loaded. If the room still isn’t visible, re-check the console for the unknown-key error above, and confirm you’re embedding the right snippet.

Programmatic embed: did you call init()?

The two install methods behave differently.

The one-line loader carries the project key in the URL and initializes the widget for you. There is no init() call to forget:

<script src="https://room.patchrooms.com/v1/patchrooms/pr_xxx.js"></script>

The programmatic embed does nothing until you call Patchrooms.init(...):

<script src="https://room.patchrooms.com/v1/patchrooms.js"></script>
<script>Patchrooms.init({ projectKey: 'pr_xxx' });</script>

If you load patchrooms.js but never call init, the room never mounts. Make sure the init call:

• runs after the bundle script (so window.Patchrooms exists), and
• actually executes — in a single-page app, place it where your app boots, not inside a route that may not have run yet.

If projectKey is missing from your init() call, the SDK throws synchronously:

Patchrooms.init: projectKey is required

Pass a valid projectKey to fix it.

Wrong project key

A project key looks like pr_ followed by a unique string (for example pr_a1b2c3). Symptoms of a wrong key:

• The loader logs [Patchrooms] unknown project key: … and no room appears.
• The room mounts, but reports never reach your dashboard. In the Network tab you’ll see requests to /ingest/config, /ingest/channels, or /ingest/report returning 401 with body {"error":"invalid_project_key_or_origin"}.

To fix it:

1. Copy the project key from your project’s settings in the Patchrooms dashboard.
2. Paste it into the script URL (loader) or the init({ projectKey: '…' }) call (programmatic), replacing pr_xxx. The key must match exactly.
3. Reload and confirm the unknown-key error is gone and ingest requests return 200.

401 with the right key?

A project can restrict which website origins may send reports. If you’ve set an allowed-origins list, requests from any other origin are rejected with the same 401 invalid_project_key_or_origin, even when the key is correct. Add the origin you’re embedding from to your project’s allowed origins, or clear the list to accept any origin.

Script blocked or CSP

If your site sends a Content Security Policy header, the browser blocks the Patchrooms script and its network calls unless room.patchrooms.com is explicitly allowed. The console shows a message like:

Refused to load the script 'https://room.patchrooms.com/v1/...'
because it violates the following Content Security Policy directive: "script-src ...".

Patchrooms needs two CSP directives:

• script-src — to load the widget bundle (and, with the one-line loader, the per-project loader).
• connect-src — for the widget’s fetch calls to the ingest API (/ingest/config, /ingest/channels, /ingest/report, and screenshot/audio uploads).

Add https://room.patchrooms.com to both. A minimal policy looks like:

Content-Security-Policy: script-src 'self' https://room.patchrooms.com; connect-src 'self' https://room.patchrooms.com;

Other directives

The widget itself only needs script-src and connect-src for room.patchrooms.com. It doesn’t load images or media into the customer page, so directives like img-src and media-src don’t affect the embedded widget — screenshots and audio are rendered in the Patchrooms dashboard, not on your page.

After updating the policy, hard-reload the page (the browser caches CSP-blocked resources as failures) and confirm the script request now returns 200.

Ad blockers and extensions

Privacy extensions and ad blockers can also drop third-party scripts. If the Network tab shows the request as blocked but your CSP allows room.patchrooms.com, test in a private/incognito window with extensions disabled to rule this out.

Privacy and captured data

Every report carries a small context blob — the page URL, viewport size, and user agent — plus whatever blocks the reporter adds (text, screenshots, audio, selections). If you need to know exactly what is collected and where it’s stored before rolling Patchrooms out, see the Privacy & data page.