The website snippet is uMarker’s primary capture surface. You paste one <script> tag into your
site and — once the project is published and that host is on its allowed list — a feedback launcher
appears for every visitor: no login, no install, no account. A visitor clicks it, points at
what’s wrong, writes a sentence, and sends. The report lands in your inbox with the screenshot, the
numbered pins and the notes written into them, the page address and the device already attached.
If the project is in Technicalcapture mode,
the console output, the failed requests and the rest of the technical record come with it.
Do this first. A project serves only the hosts you list on it. A project with no domains serves
nowhere, and the snippet will stay silent on every page you paste it into. This is not a safety
default you can leave blank: domains are the unit your plan counts, and the same list is what the
browser extension uses to decide which project a page belongs to.
Open your project and go to the Widget tab, Setup.
Add each host you’ll collect feedback on, one per row, hostname only:
example.com
www.example.com
staging.example.com
Save. You can’t publish a project with an empty list.
Publishing is what makes the widget live: a project in Draft renders nothing, anywhere. The
toggle sits in the project header and on the projects list, and flipping it back to Draft switches
the widget off everywhere without touching the snippet on your site.
Publishing is necessary rather than sufficient. A project can read Published in its header and
still serve nothing, for three reasons this page comes back to: the Snippet switch on
Widget → Snippet is off, it has no live domain left, or a plan downgrade has paused it.
Publishing mints the project’s public key if it doesn’t have one yet: a md_ identifier
followed by 40 characters:
md_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
The key is public by design (it sits in your page source) and is never an authorization secret. It
resolves which project a page belongs to, and unlocks only that project’s public widget surfaces:
feedback, surveys, and announcements. The server re-validates the origin, the plan, and every field
on ingest. Moving a project back to Draft keeps the key, so the snippet
already embedded on your site doesn’t break when you publish again.
The snippet does two things. First, the inline shim checks the project’s capture mode as this
browser last saw it (the widget caches it under md_mode_<your key> on every load). Only if that was
Technical does it start buffering console output and errors immediately, so a failure that
happens before the widget has finished loading still lands in the report. For a Normal project, and
on a visitor’s very first page load, it records nothing. Then it appends the real bundle with
async, so it never blocks your first render.
Two attributes carry everything:
Attribute
Value
Purpose
src
https://api.umarker.com/widget/v1.js
The bundle. The widget reads its API base from this script’s own origin, so this must be the API host.
The launcher and the capture tool mount inside a Shadow DOM with an all:initial host reset, so
your CSS can’t style them and their styles can’t reach your page. JavaScript is a separate
story: see What the widget touches on your page below.
Fail-silent
If the key is unknown or revoked, the origin isn’t on the allowed list, the project is in Draft,
or the bundle is blocked, the widget simply does not mount. It never throws into your page.
Asynchronous
The bundle loads with async, and nothing is appended to your page until its config request
comes back — so it never competes with your first render.
Idempotent
A window.__umarkerLoaded guard means a second copy of the snippet returns immediately, so a
reporter never sees two launchers. It is first-script-wins and it never compares keys: remove
a stale snippet, don’t paste the new one beside it. If the browser extension is also active on
the page, it takes over and removes the snippet’s launcher.
Shadow DOM isolates markup and CSS. It does nothing for JavaScript. In Technical mode the widget
reaches into three of your page’s globals — deliberately, because that is how console output and
failed requests get into the report. In Normal mode it wraps none of them:
console.log/info/warn/error are wrapped to record what they print, then the original is called
with the original arguments.
fetch and XMLHttpRequest are wrapped to record the requests your page makes: method, URL
(secret-looking values blanked), status and timing, with failures flagged. Headers and bodies are
never read. Your own code sees no difference: the original Response is handed back and the original
error is re-thrown, untouched.
Its own globals are namespaced: window.uMarker and the window.__md… / window.__umarker… keys.
Nothing else on your page is modified.
Everything goes to the API origin and nowhere else. Nine endpoints, all open to any origin (CORS)
and rate-limited server-side. Three GETs fire on every page load — allowlist all three at a
proxy or WAF, or surveys and the changelog feed go quietly dead:
GET /api/public/widget/{key}/config: the project’s settings, plus
targeting, evaluated before it mounts.
GET /api/public/widget/{key}/survey: the one survey eligible for this
page, if any.
GET /api/public/widget/{key}/feed: live announcements and the
“What’s new” entries.
The rest are POSTs. POST …/feedback (a report) and POST …/survey/{id}/respond (a survey answer)
need a visitor to act. The four seen/dismiss/click beacons do not: a live survey or announcement
fires its present / seen beacon the moment it renders, once per visitor per item. Allowlist the
POSTs too, or a live announcement will be blocked on a page nobody clicked.
Defaults, all configurable by the platform operator: reports and survey answers share 20 per
minute per key and 30 per minute per source IP; the three reads get 600 per minute per
source IP, and the beacons the same in a bucket of their own.
If your site sends a strict CSP, allow the widget the three things it needs. Everything it loads
comes from one origin; there is no third-party CDN in the path:
script-src: the inline snippet (a nonce or hash, or 'unsafe-inline') and api.umarker.com
for /widget/v1.js, the shared capture tool, and the screenshot library, which is self-hosted
at /widget/vendor/ on that same origin.
connect-src: api.umarker.com, for every request in Endpoints above.
img-src: allow data: so the screenshot can be rendered and previewed in the browser.
If the snippet runs inside an <iframe>, the tab capture also needs the frame to allow it
(allow="display-capture"); without that the widget draws the page itself, as it does when a visitor
declines.
uMarker attaches no visitor identity of its own: an anonymous snippet report is written with no
user and no email. If your site already knows who the visitor is, attach their email and any custom
data so reports arrive attributed.
That is a claim about our fields, not about the report as an artefact. In Technical mode the
console output and the request URLs are captured on every report, anonymous ones included, and they
carry whatever your application put there — a logged-in user’s email in a debug line, an account id in a
failing request path. Turn on Redaction in Widget → Setup and both are scrubbed in the
browser before anything is sent. See
Capture context & redaction.
Call identify()before the snippet loads where you can. Two reasons. It merges rather than
replaces — a later call overwrites only the fields you pass and leaves the rest in place, so there
is no way to clear an identity on sign-out short of a page load. And the identified users only
audience rule is first decided the moment the config response arrives: an identity that lands later
still counts, but the widget appears only once it does, so identifying first avoids a visible delay.
Once the bundle has loaded, window.uMarker.identify('visitor@example.com', { … }) does the same
thing.
email must be a real email address or null, and data must be an object serializing to under
16 KB of JSON. Both are validated when the report is sent, not when you call identify() —
so passing an internal user id where the email goes rejects the whole report, and the visitor’s
words, pins and screenshot go with it. Use your real email field, or leave it null.
The data object is stored with the report. It is displayed on the
report page only for keys that match a custom field defined on the
workspace — a key with no matching field is kept but never shown, and custom fields are a
Professional-and-above feature.
The widget exposes two calls, so you can put feedback behind a menu item or a help link instead of
only our launcher. Guard them — they are defined at the end of the mount, so they exist only
once the widget has actually mounted on this page:
if (window.uMarker?.open) window.uMarker.open(); // opens the capture tool
if (window.uMarker?.hasDraft) window.uMarker.hasDraft(); // true if an unsent report waits here
Neither is defined while the config request is still in flight, on a page
targeting rules exclude, once a frequency cap is spent, or when the
browser extension has taken the page over. Unguarded, the call throws a TypeError inside your own
script. The identify queue above has no such problem: window.uMarker is an array you create
yourself, and the bundle drains it and replaces it with the real object the moment it runs — long
before any of this.
Load a page on one of your allowed domains. The launcher appears in the corner set by your
customization, bottom-right by default.
Click it. In Chrome and Edge your browser first asks to share this tab — one line on screen
says why — so the screenshot is the browser’s own pixels. Decline it (or use another browser) and
the widget draws the page itself instead; the report sends either way. The capture tool then takes
over the page: hover an element and it highlights with its box model. Click to drop a numbered pin
and write a note into it.
Each note you save takes a picture of the screen you’re on (the tool hides itself for that
instant). Press Review, then Submit for review to send. A Report sent confirmation follows.
On Widget → Snippet, the status panel flips from Waiting for your widget to Your widget
is live on its own; it polls every few seconds, so there is nothing to reload. The relative
last-seen time lives on the project Overview instead.
Detection is best-effort presence signalling. The first load is stamped immediately and the panel
picks it up within a few seconds; after that the stamp is refreshed at most once an hour, so
last seen on the Overview can be up to an hour behind.
Open your inbox. The report is there. The inbox list doesn’t say where a
report came from — open it, and the Reporter row shows the visitor’s email, or
Public visitor when they didn’t give one.
A rejected request (offline, flaky connection, a 5xx from a deploy) writes the report to the
visitor’s own browser for seven days and pushes it once, silently, on their next visit. If
storage is too full to hold it, the screenshot is dropped and the words are kept: the image can be
taken again, what the visitor wrote cannot.
Permanent rejections (a revoked key, a disabled widget, invalid data) are not saved, because
retrying them would fail forever. The one exception is a 429: both the per-minute throttle and the
daily cap succeed on a later attempt, so those are kept.
Rotate key issues a new key and revokes the old one. The old snippet stops collecting
immediately, so update your site with the new one.
Revoke clears the key entirely. The widget stops rendering everywhere, and an in-flight
submission from a revoked key is refused with 410.
Both reset the install status to Not installed yet, because the old snippet is dead and the new
one hasn’t reported in.
Because the key is public by design, rotation is your response to a scraped or abused key. In the
meantime the allowed-domain check, the per-key and per-IP rate limits, and the payload caps are what
actually protect you.
Enforced server-side. On a Technical report, console logs, failed requests and the rest of
the technical record are trimmed to the most recent entries rather than refused — a chatty page
still submits. A Normal report carries none of them. Everything else over a cap is refused,
and the visitor is shown the server’s own reply verbatim. Those replies are plain sentences in the
brand’s language: an oversized screenshot says so in words rather than as a character count, and a
note or pin note over its limit is named as the visitor knows it, not by its field path. A refused report is never
kept as a draft; only 429 and 5xx are.