Managed widget docs

ElementSnap v1 is a managed SaaS for pinned visual feedback in internal and admin applications. The widget stays lightweight, framework-agnostic, and focused on precise page comments rather than replay or analytics.

Quick start

Install one script, provide a short-lived auth token from your backend, and tell the widget how to normalize the current route.

<script src="https://cdn.elementsnap.com/vfw.min.js"></script>
<script>
  window.VisualFeedbackWidget.init({
    workspaceKey: "acme-admin",
    mode: "managed",
    getAuthToken: async () => {
      const res = await fetch("/api/elementsnap/widget-token");
      const json = await res.json();
      return json.token;
    },
    routeResolver: () => ({
      pageId: window.location.pathname,
      pageTitle: document.title,
      pageUrl: window.location.pathname + window.location.search,
    }),
    user: {
      id: "u_123",
      name: "George",
      role: "manager"
    }
  });
</script>

What ships in v1

Floating launcher with unresolved badge counts

Feedback mode with click-to-pin composer

Persistent page pins that survive refreshes

This Page and All Comments panels

Resolve actions for managers

Clear-all confirmation flow for managers

Init contract

Field	Type	Required	Description
workspaceKey	string	Required	The workspace key provisioned in the ElementSnap control plane.
mode	"managed"	Required	Managed SaaS is the only v1 launch mode.
getAuthToken	() => Promise<string>	Required	Returns a short-lived HS256 JWT signed by your backend with the workspace secret.
routeResolver	() => { pageId, pageTitle, pageUrl? }	Required	Normalizes route context so comments stay grouped correctly in SPAs and admin apps.
user	object	Optional	Supplies the current actor ID, name, and reviewer or manager role.
permissions	object	Optional	Optional client-side hints for UI actions. Server-side permissions still come from the signed token.
theme	object	Optional	Small appearance overrides if you need to nudge accent or surface colors.
onEvent	(event) => void	Optional	Receives lightweight widget lifecycle events such as ready, comment created, and comment resolved.
navigateToPage	(comment) => void	Optional	Overrides default location navigation for SPA routing when a reviewer clicks Go to page.

Managed API

GET/api/widget/comments?pageId=...

Fetch comments for the current normalized page.

GET/api/widget/comments

Fetch every comment in the workspace.

POST/api/widget/comments

Create a pinned feedback item with page metadata and normalized pin coordinates.

PATCH/api/widget/comments/:id

Resolve an existing feedback item.

DELETE/api/widget/comments?scope=all

Clear all workspace comments after explicit confirmation. Manager-only in managed v1.

Auth model

Your backend signs a short-lived HS256 JWT with the workspace secret provisioned in the dashboard.

The token includes workspace key, user id, role, optional permissions, and expiry.

The widget never ships the long-lived workspace signing secret to the browser.

ElementSnap validates the token on every managed widget request.

Try it yourself

Use the public sandbox to see the full managed workflow, or sign in to your dashboard to copy the install snippet and rotate your workspace signing secret.