Widget documentation

Add the ZebraFeedback widget to your site with one script tag. This page covers embedding, script attributes, and the JavaScript API for metadata and callbacks.

Quick start

Get your widget key from the dashboard: Websites → your website → Embed. Add this script before </body> (use your own data-widget-key):

<script
  src="https://zebrafeedback.com/widget.js"
  data-widget-key="YOUR_WIDGET_KEY"
  async
></script>

The script loads asynchronously. When the current page matches a survey's "Show button" rules (configured in the dashboard), a floating feedback button appears. Click it to open the survey.

Script attributes

Attribute	Required	Description
data-widget-key	Yes	Your website's widget key from the dashboard. The widget will not load without it.
data-api	No	API base URL. Defaults to `https://zebrafeedback.com`. Set for self-hosting or local dev (e.g. `http://localhost:3000`).
data-position	No	Position of the floating button: `left` or `right`. Defaults to `right`. Can also be overridden per-website in the dashboard.
data-metadata	No	JSON object of metadata to attach to every response (e.g. app version, environment). Example: `data-metadata='{"appVersion":"1.0.0"}'`

JavaScript API

After the script loads, window.ZebraFeedback exposes these methods and properties. Use them to set metadata or run code when the widget is ready or when the user opens the popup.

ZebraFeedback.setMetadata(obj)

Attach or replace dynamic metadata sent with the next (and subsequent) response submissions. Useful for values that change at runtime (e.g. current route, feature flags). Merged with any static data-metadata from the script tag.

ZebraFeedback.setMetadata({ appVersion: "1.2.0", plan: "pro" });

ZebraFeedback.onPopupOpen(fn)

Register a callback that runs whenever the user opens the popup (clicks the feedback button and the survey list or form is shown). Use it to inject or update metadata right before the user might submit, so each response has up-to-date context.

ZebraFeedback.onPopupOpen(function () {
  ZebraFeedback.setMetadata({
    route: window.location.pathname,
    plan: "pro"
  });
});

ZebraFeedback.ready(fn)

Run a callback when the widget has loaded and fetched its config. If the widget is already ready, the callback runs immediately. Use it to set initial metadata or other one-time setup.

if (window.ZebraFeedback) {
  ZebraFeedback.ready(function () {
    ZebraFeedback.setMetadata({ environment: "production" });
  });
}

ZebraFeedback.whenReady

A Promise that resolves when the widget is ready. Useful with async/await.

await ZebraFeedback.whenReady;
ZebraFeedback.setMetadata({ loadedAt: new Date().toISOString() });

Metadata limits

Metadata is stored with each response so you can filter and analyze by version, plan, route, etc. Server-side limits:

Maximum 15 keys (extra keys are ignored)
Each key and value: maximum 36 characters (truncated if longer)
Keys and values are sanitized for safety

Show button rules

You configure when the feedback button appears in the dashboard per survey. Rules can target: all pages, URL contains/equals a path, time on page (seconds), and metadata (e.g. show only when metadata.plan === "pro"). Multiple conditions are combined with AND or OR, depending on the survey configuration. The widget re-evaluates on navigation; for single-page apps it listens to hashchange, popstate, and the History API, and hash routes like #/pricing are normalized to path /pricing.

One response per user

In the dashboard you can set a survey to "Allow only one response per user". When enabled, the widget stores and prevents duplicate submissions by storing the submitted survey IDs in localStorage.

Origin and CORS

Widget config and response submission are restricted by origin: the request Origin host must match the website's configured domain in the dashboard. Mismatched origins receive 403. Ensure your website's domain in ZebraFeedback matches the host where the script is embedded.

← Back