Dashboard Manual Pricing Use Cases
Manual

Tracking

Dregs builds user profiles from two sources: frontend events captured by the dregs.js tracking script in the browser, and backend events sent from your server via the REST API. Together, they show Dregs what each user does in the browser and what happens on your server.

Frontend Tracking

The primary integration point is dregs.js, a lightweight JavaScript library that collects device intelligence and behavioral data from your website. It fingerprints browsers without cookies, tracks user actions, and feeds everything into the scoring engine. Dregs collects no personally identifiable information automatically — you control exactly what data gets sent.

Installation

Add the following snippet to every page where you want to track users. The queue pattern buffers calls made before the script finishes loading and replays them automatically. 

<script>
  window.dregs = window.dregs || function() {
    (window.dregs.q = window.dregs.q || []).push(arguments);
  };
  dregs('init', { key: 'pk_your_public_key_here' });
</script>
<script src="https://dregs.com/dregs.js" async></script>

The stub function at the top creates a lightweight queue. Calls to dregs() before the real script loads land in dregs.q and run once the script is ready. You can safely call dregs.identify() and dregs.track() anywhere on the page regardless of load order.

dregs('init', options)

Initializes the tracker. Call this before any other method. Triggers device fingerprinting and sends a dregs_init event automatically. 

dregs('init', { key: 'pk_your_public_key_here' });

Options:

  • key (required) — Your public API key, starting with pk_. Never use a secret key (sk_) in client-side code.

Fingerprinting begins as soon as the page's load event fires. Dregs captures the device fingerprint, browser signals, and page URL, then sends them in the initialization event.

dregs.identify(id, data)

Associates the current session with a known user identity. Call this after login, after signup, or on any authenticated page load. 

dregs.identify('user_12345', {
  name: 'Jane Cooper',
  email: 'jane@example.com',
  plan: 'pro',
  company: 'Acme Inc'
});

Parameters:

  • id (required) — A string or number that uniquely identifies the user in your system. This becomes the identity's ID in Dregs.
  • data (optional) — An object of key-value pairs with additional user information. Dregs extracts name and email for display in the dashboard and stores all other fields for analysis.

Calling identify() sends a dregs_identify event and attaches the identity to all subsequent events in the session. If you call it multiple times with different IDs, Dregs uses the most recent identity.

dregs.track(type, data)

Sends a custom event. Use this to track user actions that feed into behavioral scoring. 

dregs.track('form_submit', { form: 'signup', source: 'landing_page' });

Parameters:

  • type (required) — The event name. Use only lowercase letters, numbers, and underscores. Maximum 100 characters. Cannot start with dregs_ (that prefix is reserved for system events).
  • data (optional) — An object of key-value pairs with event context. Any data relevant to the action: form names, product IDs, amounts, categories.

Reserved fields: Keys starting with an underscore (_) are reserved for Dregs internal use. Avoid prefixing your custom data keys with underscores.

dregs.fingerprint()

Returns a Promise that resolves to the device's fingerprint string. The fingerprint becomes available after initialization completes. If called before the fingerprint is ready, it polls until available (up to 10 seconds before timing out). 

const fp = await dregs.fingerprint();
console.log(fp); // "a1b2c3d4e5fa1b2c3d4e5fa1b2c3d4e5"

Use this when you need to pass the device fingerprint to your own backend — for example, to query the Dregs API for device information server-side.

dregs.getDeviceInfo()

Returns a Promise that resolves to the device information object from the Dregs API. Waits for the fingerprint, then fetches the device record. Requires a valid public key to authenticate. 

const device = await dregs.getDeviceInfo();
if (device) {
  console.log(device.ip);        // IP address
  console.log(device.city);      // Geolocation city
  console.log(device.country);   // Geolocation country
}

Returns null on the first page load, before the server processes the init event. On subsequent loads, it returns the full device record including geolocation and session history.

dregs.version / dregs.isInitialized()

dregs.version returns the version string of the loaded dregs.js library. dregs.isInitialized() returns true once init() has been called and fingerprinting has completed — useful for conditional logic that depends on the tracker being ready.

What's Collected Automatically

When the tracking script initializes, it collects device signals used to generate the fingerprint: user agent, browser language and platform, screen resolution and color depth, timezone, hardware concurrency, device memory, canvas rendering fingerprint, WebGL renderer information, and installed browser plugins.

None of these signals contain personally identifiable information. Dregs hashes them into a fingerprint that uniquely and opaquely identifies the device.

Every event also automatically includes the current page URL, the device fingerprint, the current identity (if identify() has been called), and a client timestamp. The server adds the IP address and geolocation when processing the event.

Backend Tracking

Much of what matters happens outside the browser. Server-side actions like payment processing, account suspensions, privilege escalations, and API calls often carry the strongest signals for fraud detection — and your backend is the only place that sees them.

Dregs accepts events from your server via the REST API. Send a POST request to /api/events authenticated with your credential's secret key (not the public key used by the tracking script). The event includes the identity it belongs to, and Dregs stitches it into the same timeline alongside that identity's frontend events.

Sending Backend Events

A backend event is an HTTP POST to /api/events with a JSON body containing the event type, optional event data, and the identity to associate it with. The identity object includes the user's ID (the same ID you use in dregs.identify()) and optionally any profile data you want to keep current. 

POST /api/events
Authorization: Bearer sk_your_secret_key
Content-Type: application/json

{
  "type": "subscription_renewed",
  "data": {
    "plan": "pro",
    "amount": 49.99,
    "period": "monthly"
  },
  "identity": {
    "id": "user-123",
    "data": {
      "name": "Jane Cooper",
      "email": "jane@example.com",
      "plan": "pro",
      "signupDate": "2025-11-15"
    }
  }
}

The identity.data fields are optional but useful. Each backend event lets you update the identity's profile with information only your server knows: plan tier, account age, phone number, last login time, or any other attributes that help Dregs score more accurately.

Idempotent Event IDs

You can optionally include an id field on the event with an identifier from your own system (up to 64 characters, cannot start with dregs-). If the same id arrives twice for the same account, Dregs silently deduplicates the second request — storing no duplicate row and leaving the monthly event count unchanged. This makes retries and resyncs safe. 

POST /api/events
Authorization: Bearer sk_your_secret_key
Content-Type: application/json

{
  "id": "stripe_evt_1Q3abc",
  "type": "subscription_renewed",
  "data": { "plan": "pro" },
  "identity": { "id": "user-123" }
}

If you omit the id, Dregs generates one of the form dregs-{uuid} and returns it in the response alongside the fingerprint. Every event always has an ID you can use to reconcile later.

What to Track from the Backend

Backend events matter most for actions that either bypass the browser or require server-side verification:

  • Payment events — charges, refunds, subscription changes, failed payments
  • Administrative actions — role changes, feature grants, manual overrides
  • API activity — direct API usage that bypasses the frontend entirely
  • Background processes — scheduled jobs, automated workflows, batch operations triggered by the user
  • Security events — password resets, MFA changes, session revocations

Avoid double-counting. If the frontend tracking script already records an action, you generally don't need to send it again from the backend. Focus backend tracking on events that only your server can observe.

Identity Stitching

The identity ID ties everything together. As long as the ID you pass in backend events matches what you pass to dregs.identify() on the frontend, Dregs merges everything into a single profile. Frontend events bring device fingerprints and browser behavior. Backend events bring server-verified actions and richer profile data. Together, they produce scores neither source could achieve alone.

Backend events carry no device fingerprint (there is no browser to fingerprint), so they do not contribute to device-related signals like Uniqueness. But they enrich Authenticity (through profile data), Behavior (through action patterns), and overall confidence (through event volume).

A single identity may combine frontend and backend events, all visible in a unified timeline on the dashboard. When you investigate a user, you see what they did in their browser alongside what your server recorded.

← Getting Started
Identities →