Skip to content
Sign inRequest access

Install the website snippet

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 Technical capture 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.

  1. Open your project and go to the Widget tab, Setup.

  2. Add each host you’ll collect feedback on, one per row, hostname only:

    example.com
    www.example.com
    staging.example.com
  3. 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.

Copy the snippet from Widget → Snippet rather than this example; it already contains your key.

index.html
<script>
(function(w,d){
var t=0;try{t=w.localStorage.getItem('md_mode_md_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')==='technical';}catch(e){}
if(t&&!w.__mdCap){
w.__mdCap=1;
var L=w.__mdLogs=w.__mdLogs||[];
var rec=function(lvl,msg){try{L.push({level:lvl,message:String(msg).slice(0,2000)});if(L.length>200)L.shift();}catch(e){}};
['log','info','warn','error'].forEach(function(k){var o=console[k];if(o)console[k]=function(){try{rec(k,Array.prototype.map.call(arguments,String).join(' '));}catch(e){}return o.apply(console,arguments);};});
w.addEventListener('error',function(e){rec('error',(e.message||'Script error')+' @ '+(e.filename||'')+':'+(e.lineno||''));},true);
w.addEventListener('unhandledrejection',function(e){var m='Unhandled promise rejection';try{var r=e&&e.reason;m+=': '+((r&&(r.stack||r.message))||String(r));}catch(x){}rec('error',m);});
}
var s=d.createElement('script');
s.async=1; s.src='https://api.umarker.com/widget/v1.js'; s.setAttribute('data-umarker-key','md_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
(d.head||d.documentElement).appendChild(s);
})(window,document);
</script>

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.
data-umarker-key your md_… key Resolves the report to your project.

Shadow-DOM isolated

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.

After the snippet
<script>
window.uMarker = window.uMarker || [];
window.uMarker.push(['identify', {
email: 'visitor@example.com',
data: { plan: 'pro', userId: 42, appVersion: '3.1.0' }
}]);
</script>

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.

  1. Load a page on one of your allowed domains. The launcher appears in the corner set by your customization, bottom-right by default.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

If a send fails, the visitor’s words survive

Section titled “If a send fails, the visitor’s words survive”

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.

Widget → Snippet has a danger zone:

  • 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.

Field Limit
Comment 5,000 characters, required
Pins per report 50, each with up to 5,000 characters of note
Screenshot 12 MB decoded
Console logs (Technical) the most recent 200 entries
Failed requests (Technical) the most recent 20
Custom data (identify) 16 KB of JSON
page_url an http/https URL, up to 2,048 characters
Reports per day (Free plan) 5 from the anonymous public surface