Simple Commenter Logo

JS API

The JS API lets your application control Simple Commenter directly. The two things most teams use it for:

  1. Log your users in automatically. If someone is already signed into your product, they should never see a Simple Commenter login. Your backend vouches for them with a signed hash, and the widget treats them as logged in.
  2. Decide who sees the widget. Keep the widget invisible for everyone, then enable it from your own code for exactly the accounts that should give feedback: a beta cohort, a specific customer, an internal flag.

The 60-second version

Enable the JS API under Project settings, Developers, copy your secret, and add this to your page:

<script>
  window.simpleCommenterSettings = {
    user: {
      email: "jane@acme.com",        // who is signed into YOUR app
      name: "Jane Cooper",
      externalId: "usr_123",         // optional: your stable user id
    },
    userHash: "REPLACE_WITH_HASH",   // computed on your backend, see below
  };
</script>
<script src="https://www.simplecommenter.com/js/comments.min.js?id=sc_your_project_key" async></script>

The hash is one line on your backend:

// Node.js
const crypto = require("crypto");
const userHash = crypto
  .createHmac("sha256", process.env.SC_PROJECT_SECRET)
  .update(`${user.id}:${user.email}`) // or just user.email if you skip externalId
  .digest("hex");

That is the whole integration. The visitor is now a recognized commenter: no magic link, no login popup, comments attributed to their name.

Important: The hash must be computed on your server. Never put your project secret in frontend code, and never compute the hash in the browser. See Identity verification for why this matters and for examples in other languages.

Calling the widget at any time

Everything the settings object does is also available as a function call, which is what you want in a SPA or when the decision happens after page load:

SimpleCommenter("boot", {
  user: { email: "jane@acme.com", name: "Jane Cooper", externalId: "usr_123" },
  userHash: hashFromYourBackend,
});

SimpleCommenter(...) is safe to call before the script has loaded. Calls are queued and run in order once it arrives. There is nothing to await and no race condition to think about.

When to use it

| Situation | Use | | --- | --- | | Your users are already logged into your product | JS API with identity verification | | You want feedback from a subset of accounts only | Login-required visibility + JS API, see SaaS setup | | External clients review a site, no account system | Regular magic link login, no JS API needed | | WordPress site | The WordPress plugin does this for you already | | Provisioning users from your backend, server-to-server | The REST API, which composes with everything here |

Next steps

Was this page helpful?