Dregs
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 give Dregs a complete picture of 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. No personally identifiable information is collected 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 ensures calls made before the script finishes loading are buffered and replayed 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. Any calls to dregs() before the real script loads are stored in dregs.q and processed once the script is ready. This means you can safely call dregs.identify() and dregs.track() anywhere on the page without worrying about load order.

dregs('init', options)

Initializes the tracker. Must be called 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. The device fingerprint, browser signals, and page URL are captured and sent to Dregs 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. All other fields are stored and available 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, the most recent identity is used.

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. Must contain 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 is 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"

This is useful 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 to be available, 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 if the device hasn't been seen before (first page load before the server has processed 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 if init() has been called and fingerprinting has completed — useful for conditional logic when you need to ensure the tracker is 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. They are hashed into a fingerprint and sent to Dregs to uniquely and opaquely identify 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

Not everything important happens in 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. You 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 is an opportunity to update the identity's profile data 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.

What to Track from the Backend

Backend events are most valuable for actions that either don't happen in the browser or that you need to verify server-side:

  • 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 an action is already tracked by the frontend tracking script, 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 key that ties everything together is the identity ID. 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 identity profile. Frontend events bring device fingerprints and browser behavior. Backend events bring server-verified actions and richer profile data. Together, they produce scores that neither source could achieve alone.

Backend events do not include a device fingerprint (there is no browser to fingerprint), so they won't 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 in Dregs may have a combination of frontend and backend events, all visible in a unified timeline on the dashboard. When you investigate a user, you see the complete picture of what they did in their browser alongside what your server recorded.

← Getting Started
Identities →