JS API Reference

All interaction goes through one global function:

SimpleCommenter("command", ...args);

The function exists as soon as our loader script runs, and calls made even earlier are queued automatically. You never need to wait for a ready state before calling anything.

The settings object

window.simpleCommenterSettings is read once when the widget starts. Setting it before the script tag is equivalent to calling boot with the same values.

window.simpleCommenterSettings = {
  user: {
    email: "jane@acme.com",  // required for identification
    name: "Jane Cooper",     // shown on comments
    externalId: "usr_123",   // optional, your stable user id
  },
  userHash: "...",           // required unless unverified mode is on
};

Commands

boot

Starts the widget and identifies the user in one call. This is the main entry point, and it is idempotent: booting with the same user twice does nothing.

SimpleCommenter("boot", { user: { email, name, externalId }, userHash });

On a login-protected project, boot is also what makes the widget appear at all: without it (or another activation, like a magic link), visitors get nothing, not even a script download.

identify

Identifies or switches the user without touching visibility. Booting with user A and later identifying user B switches the session to B.

SimpleCommenter("identify", { user: { email, name, externalId }, userHash });

update

Updates attributes of the current user, for example after they change their display name in your app. Requires a hash covering the new values.

SimpleCommenter("update", {
  user: { email: "jane@acme.com", name: "Jane C." },
  userHash: "...",
});

show / hide

Controls widget visibility for this visitor. Both persist across pageviews in this browser until the opposite call is made, so calling hide once in your "feedback off" code path is enough.

SimpleCommenter("show");
SimpleCommenter("hide");

mode

Sets the widget mode directly: "view" (see comments), "active" (leave comments), "disabled" (hidden).

SimpleCommenter("mode", "active");

open / close

Opens or closes the comment drawer, for example from your own "Give feedback" button:

document
  .querySelector("#feedback-btn")
  .addEventListener("click", () => SimpleCommenter("open"));

on / off

Subscribe to widget events. Unsubscribe with off and the same function reference.

function onComment(payload) {
  analytics.track("feedback_left", payload);
}
SimpleCommenter("on", "comment:created", onComment);
SimpleCommenter("off", "comment:created", onComment);

logout

Ends the widget session for the current user. The widget stays on the page in its anonymous state (which on a login-protected project means it disappears).

SimpleCommenter("logout");

shutdown

Logs out and removes the widget from the page entirely. Call this when the user logs out of your app, so the next person on a shared machine cannot comment as them.

SimpleCommenter("shutdown");

Events

| Event | Fires when | Payload | | --- | --- | --- | | ready | The widget finished initializing | {} | | identified | A user was successfully identified | { email, name, role } | | opened | The comment drawer opened | {} | | closed | The comment drawer closed | {} | | mode:changed | The mode changed (by the user or by API) | { mode } | | comment:created | The current user posted a comment | { commentNumber, slug } |

Payloads only ever describe the current visitor's own actions. Errors thrown inside your listeners are caught and logged; they cannot break the widget.

SPA notes

• The script tag loads once; you do not need to re-add it on route changes.
• Call boot after your auth state resolves. Calling it in a React useEffect, a Vue onMounted, or after your login redirect all work.
• On logout in your app, call SimpleCommenter("shutdown").