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.
| Attribute | Required | Purpose |
|---|---|---|
| data-widget-id | Yes | The widget to load. Without it the loader logs a warning and does nothing. |
| data-inline-target | No | CSS selector of an element to render the widget inside. Leave it out for a floating widget. |
| data-api-url | No | Overrides the API origin. Only needed for self-hosted or local development setups. |
| data-widget-url | No | Overrides 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 loadedon 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.
| Trigger | Behavior |
|---|---|
| floating_button | Shows a launcher button. The visitor clicks to open. |
| immediate | Opens as soon as the widget loads. |
| delay | Opens after a number of seconds you choose. |
| scroll | Opens after the visitor scrolls past a percentage of the page. |
| exit_intent | Opens when the cursor leaves the top of the viewport. |
| custom | Opens 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_IDBefore you ship, check the supported browsers.