Developer docs

Widget reference

The widget is one script tag on your staging site. It stays invisible to ordinary visitors, wakes only for an invited tester, and mounts inside a closed Shadow DOM so its styles cannot leak into your page and your page's scripts cannot reach into it. Every request it makes is outbound from the tester's browser to DeploySeal — DeploySeal never connects to your staging network, so private, VPN-gated and password-protected environments work unchanged.

Install

Paste the snippet from Sites → your site → Install widget before the closing </body> tag. It loads asynchronously and never blocks rendering. Once the first heartbeat arrives the site shows the widget as Active and testers can be invited.

<script
  src="https://cdn.deployseal.com/ds-widget.js"
  data-ds-site-key="ds_pub_••••••••••••••••"
  data-ds-api-base="https://api.deployseal.com"
  data-ds-environment="staging"
  data-ds-build="2026.09.04-a1b2c3d"
  async
></script>

Attributes

Build marker via meta tag

<!-- Alternative to data-ds-build: read live on every page, so a
     single-page app can update it after each deploy -->
<meta name="ds-build" content="2026.09.04-a1b2c3d">

Optional markup on your own elements

<!-- Optional: a stable, deploy-proof anchor for element pins -->
<button data-ds-id="checkout-pay-now">Pay now</button>

<!-- Optional: mask the text of an element in session replays -->
<p data-ds-mask>Order for Jane Citizen, 14 Example St</p>
<p class="ds-mask">…also works as a class</p>

Allowed origins

Every widget request carries the browser's Origin header, and the API accepts it only if it exactly matches one of the site's allowed origins — scheme, host and port, compared case-insensitively, e.g. https://staging.yourstore.co.za. Requests from any other origin are rejected, which is what makes the public site key safe to ship in HTML.

• Origins are set per site under Allowed origins. An environment with its own key can carry its own list; when that list is empty the site's list applies.
• In production a site with no allowed origins rejects every widget call — the dashboard warns you until you add one.
• Regenerating an environment key invalidates the old snippet immediately.

How a tester session starts

1. A tester is invited to a campaign and receives a personalised link. Accepting it sends them to your staging URL with ?ds_cti=… appended — the campaign-tester id that is their credential. No DeploySeal account is involved.
2. The widget reads the parameter, stores it in sessionStorage (so it survives navigation within the tab), strips it from the address bar, and calls the bootstrap endpoint with the site key and that id.
3. Bootstrap succeeds only when the origin is allowed, the tester belongs to the campaign, and the campaign is active. Then the bar appears — across the top on desktop, along the bottom on a phone — with the campaign's instructions, the task list with each task's expected outcome, pins already on this page, and the tester's verdict controls. Session recording starts at this point and not before.
4. On any other page load — no id, an unknown id, a closed campaign, a disallowed origin — the widget sends the install heartbeat and stays hidden (display:none).

Continue on a phone. The tester's dashboard, the widget and the invitation email can show a QR code that encodes a one-time handoff link (/t/<code>). Scanning it on a phone redeems the code — valid once, for ten minutes — and opens the staging site with the same tester session attached, so mobile tasks are recorded against the same person.

After the seal. When the readiness report is sealed, task results and verdicts are frozen in the widget until the record is reopened; issues can still be filed against the campaign.

What the widget records

Nothing below leaves the browser without an active tester session, except the install heartbeat. URLs pass through a sanitiser that strips tokens, one-time codes and email addresses before they are sent.

Every uploaded artifact is fingerprinted with SHA-256 on receipt; the fingerprint is what the sealed record and the evidence package carry, so a screenshot or replay can be checked byte-for-byte later. See Verifying a sealed record.

Content-Security-Policy

If your staging site sends a CSP, allow the widget script, the API it calls, and the font it loads inside its shadow root (DM Sans from Bunny Fonts — no Google Fonts, no tracking). Use the hosts from your own install snippet if your deployment is self-hosted.

Content-Security-Policy:
  script-src  … https://cdn.deployseal.com;
  connect-src … https://api.deployseal.com;
  style-src   … https://fonts.bunny.net;
  font-src    … https://fonts.bunny.net;

Screenshots are rendered from the DOM in the browser, so no img-src change is needed for capture; replay and screenshot uploads go to the API host above.

Building on top? See the API reference and the webhook events reference.