Docs

Embed and JS API

One script tag puts a widget on your site. Everything else, from questions to targeting, is managed in the dashboard.

The snippet

Paste this before the closing </body> tag, or anywhere in the page. Replace YOUR_WIDGET_ID with the id from the widget's Embed tab in the dashboard.

<script async src="https://cdn.snapfeedback.app/embed.js" data-widget-id="YOUR_WIDGET_ID"></script>

The snippet loads embed.js, a loader of about 1 KB. It reads the widget id, adds the widget to the page, loads the widget runtime when needed and exposes the JavaScript API. You never reference the runtime file yourself.

Script attributes

The loader reads these attributes from its own script tag.

AttributeRequiredPurpose
data-widget-idYesThe widget to load. Without it the loader logs a warning and does nothing.
data-inline-targetNoCSS selector of an element to render the widget inside. Leave it out for a floating widget.
data-api-urlNoOverrides the API origin. Only needed for self-hosted or local development setups.
data-widget-urlNoOverrides the widget runtime URL. Only needed for local development.

JavaScript API

The loader adds a global window.SnapFeedback. Calls you make before the widget runtime finishes loading are queued and run once it is ready, so you can call the API right after the snippet.

SnapFeedback.open(); // open the widget panel
SnapFeedback.close(); // close it
SnapFeedback.reset(); // reset widget state and clear identification

// Identify the current visitor (id first, then optional attributes)
SnapFeedback.identify('user-123', { email: 'user@example.com', plan: 'pro' });

// Subscribe to events
SnapFeedback.on('submit', (data) => console.log('feedback submitted', data));
SnapFeedback.off('submit', handler);

// Read-only getters
SnapFeedback.widgetId; // the configured widget id
SnapFeedback.isLoaded; // whether the runtime has loaded

on and off support the events open, close, submit, error and step.

Identify visitors

Attributes you pass to identify() are saved only when that visitor sends a response. Calling identify() on its own writes nothing.

  • Visitors and their attributes are kept per project.
  • A later response adds new keys, overwrites keys that already exist and keeps keys it does not mention.
  • Each visitor can hold at most 20 keys. Once 20 are stored, new keys are dropped and existing keys still update.
  • Keys are 1 to 64 characters of letters, digits, underscore or dash. Values are a string of up to 500 characters, a number or a boolean. Anything else is dropped, and the answers are still saved.
  • A numeric visitor id is sent as a string. An empty id, an id over 255 characters or any other non-string id is ignored and logged to the browser console, so that response is anonymous and stores no attributes.
  • Calling identify() with a different id clears the attributes the widget held for the previous id.

Attributes come from the visitor's browser and can hold personal data such as an email. Treat them as hints that help you read a response, not as a verified identity. Do not use them for access control, billing or account matching.

Triggers

How a widget opens is set per widget in the dashboard, on the Behavior tab, not in the snippet.

TriggerBehavior
floating_buttonShows a launcher button. The visitor clicks to open.
immediateOpens as soon as the widget loads.
delayOpens after a number of seconds you choose.
scrollOpens after the visitor scrolls past a percentage of the page.
exit_intentOpens when the cursor leaves the top of the viewport.
customOpens when your page dispatches a named window event.

Open the widget from your own button

Set the widget's trigger to Custom event and choose an event name, for example sf-open. Then dispatch that event on window from your page. This works for no-code setups too, such as a tag manager tag that dispatches the event.

document.querySelector('#my-feedback-button').addEventListener('click', () => {
  window.dispatchEvent(new Event('sf-open'));
});

If you already write JavaScript, calling SnapFeedback.open() does the same thing with less setup.

Inline mode

By default the widget is a floating overlay. To render it inside an element on your page, add data-inline-target with a CSS selector.

<div id="feedback-here"></div>

<script
  async
  src="https://cdn.snapfeedback.app/embed.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-inline-target="#feedback-here"
></script>

In inline mode the widget opens inside the container on its own and the trigger is bypassed. If the selector matches no element, the widget does not render and the loader logs a warning. It does not fall back to a floating overlay.

Several widgets on one page

Add one snippet per widget, each with its own data-widget-id. Each widget renders independently, for example a floating widget plus an inline one.

One limitation today: window.SnapFeedback is a single global tied to the last embed script that runs. The JavaScript API controls only that widget. Widgets that open on their own, such as a floating button, inline, custom event or delay, all work independently. You cannot yet target a specific widget from JavaScript when several are on the page.

Hosted link

Every widget is also available as a hosted page, with no embedding needed. This is handy for email, social posts and QR codes.

https://app.snapfeedback.app/s/YOUR_WIDGET_ID

Before you ship, check the supported browsers.