Skip to Content
UsageMapDocs
Website analytics

Custom events and consent

Track sign-ups, clicks and other actions, add a consent mode, let visitors opt out, and debug the tracker.

Custom events

Page views are automatic. For anything else, call track() with an event name and up to 10 properties.

window.scf.track("signup", { plan: "free" });
window.scf.track("swap_completed", { pair: "XLM-USDC", amount_bucket: "100-1k" });

The script tag exposes the tracker as window.scf. If your code might run before the tracker has loaded, queue the call; it is replayed in order once the tracker is ready:

<script>
  window.scf = window.scf || [];
  window.scf.push(["track", "signup", { plan: "free" }]);
</script>

Custom events appear under Breakdowns → Custom events on the website dashboard, and you can use them as steps in funnels and as goals under Reports.

By default the tracker sets no cookies and stores nothing on the visitor's device. If your policy still requires consent first, turn on consent mode: the tracker then sends nothing until you call grantConsent().

<script>
  window.scf = window.scf || [];
</script>
<script
  src="https://e1.usagemap.dev/lib/1.1.0/standard.js"
  integrity="sha384-AYjFWyBUxxvOL92oDDKxAus7EAPjONT2RDrOiuPh4XUiEJNKkMaZqGVBDw4Lqn0+"
  crossorigin="anonymous"
  data-site="YOUR_SITE_KEY"
  data-consent="required"
  defer
></script>
<script>
  // Call these from your consent banner.
  function onAnalyticsConsentGiven() {
    Array.isArray(window.scf) ? window.scf.push(["grantConsent"]) : window.scf.grantConsent();
  }
  function onAnalyticsConsentWithdrawn() {
    Array.isArray(window.scf) ? window.scf.push(["revokeConsent"]) : window.scf.revokeConsent();
  }
</script>

The Snippet tab has this ready to copy: choose HTML with consent mode.

Opt-out

Give visitors an opt-out link or toggle:

window.scf.optOut(); // stops sending, and remembers it in this browser
window.scf.optIn();  // undoes it

The opt-out flag (scf_optout) is the only thing the tracker ever stores in the browser. Visitors with Global Privacy Control or Do Not Track turned on are already opted out automatically.

All tracker methods

MethodWhat it does
track(name, props?)Sends a custom event. Returns false if it was refused.
optOut() / optIn()The visitor's own choice, remembered in their browser.
grantConsent() / revokeConsent()For consent mode, called from your banner.
destroy()Stops the tracker and removes its listeners.

Debugging

There are two switches, one for each side:

Site debug mode (server side)

In the app: website → Installation check → Debug mode, for 1 minute up to 24 hours. While it is on, every answer to your site carries an X-Scf-Debug header with the verdict, for example class=suspect; reasons=domain_unverified. Look for it in the browser's network tab.

Tracker debug module (browser side)

With the npm package, call debug() from @scf-analytics/tracker/debug before init(), in development only. The console then explains what was sent and why something wasn't, for example "Global Privacy Control is on".

On this page