Events

Every action a user takes in your application becomes an event in Dregs — a complete audit trail that feeds real-time scoring. Events are the raw material of behavioral analysis, and the more you send, the sharper the picture becomes.

What Are Events

An event is a discrete record of something a user did. Dregs handles two types of events:

• Identify events — created when you call dregs.identify() to associate the current device with a user identity. This is how Dregs learns who sits behind a device.
• Custom events — created when you call dregs.track() to record a specific action. These are the behavioral building blocks: signups, logins, purchases, form submissions, and anything else worth tracking.

Dregs stores both types as events, but they serve different roles. Identify events establish the device-to-identity mapping. Custom events provide the behavioral data that feeds scoring.

What Events Capture

Every event automatically carries rich contextual data, without extra work on your part:

• Event type — the name you give the event (e.g., "signup", "purchase")
• Custom data — any key-value pairs you choose to include
• Identity — the user ID, if one has been identified on this device
• Device fingerprint — the full fingerprint of the device that generated the event
• IP address — the network address, geolocated to city and country
• URL — the page where the event occurred
• Timestamp — server-side timestamp for reliable ordering

You decide the event type and custom data. The tracking script and the Dregs backend collect everything else automatically.

Sending Events

You send events through the tracking script on your frontend or through the REST API from your backend. The two primary frontend methods are:

// Associate this device with a user identity
dregs.identify("user-123");

// Track a custom event with optional data
dregs.track("purchase", {
  plan: "pro",
  amount: 49.99,
  currency: "USD"
});

The events worth tracking depend on your application, but these are commonly valuable:

• signup — account creation, the single most important event for fraud detection
• login — session starts, revealing credential stuffing and account takeover
• purchase — transactions, critical for payment fraud patterns
• form_submit — form completions, revealing automated submissions
• password_change — security-sensitive actions that may indicate account compromise
• profile_update — data changes, revealing identity manipulation
• feature_usage — application interactions that build the behavioral baseline

Event types have no limit. Create as many as are meaningful for your application. See the Tracking page for the full API reference, including backend event tracking through the REST API.

Frontend and Backend Events

Events come from two sources: the frontend tracking script running in the browser, and your backend server through the REST API. Dregs stitches them together by identity ID, giving each identity a unified timeline of browser-side and server-side activity.

Frontend events automatically include device fingerprints and browser context. Backend events enrich the profile with server-verified data: payment history, administrative actions, and API activity the browser never sees.

See the Tracking page for complete details on both frontend and backend event tracking, including the API payload format and identity stitching.

How Events Feed Scoring

Events are the raw material of the entire scoring system. When new events arrive for an identity, Dregs re-runs its analyzers to update scores. Events contribute to each dimension as follows:

• Humanity — analyzers examine event timing intervals. Human actions vary naturally; automated scripts produce unnaturally uniform or rapid-fire patterns.
• Authenticity — analyzers check the data submitted in events (names, emails, profile fields) for consistency and plausibility.
• Uniqueness — events establish device-identity relationships. When multiple identities generate events from the same device, Uniqueness scores adjust.
• Behavior — session frequency, time-of-day patterns, IP address changes, and navigation sequences all come from event data.

More events mean higher confidence in scores. A user with three events has a preliminary score. A user with three hundred events has a score you can act on with high confidence.

The Event Stream

The Events page in the dashboard shows a real-time feed of all events flowing into your account. Filter the stream by:

• Identity — show events for a specific user
• Device — show events from a specific device fingerprint
• Free text search — search across event names, IP addresses, and identity IDs

The event stream is your primary tool for investigating specific users or incidents. When an alert fires, the event stream shows exactly what the user did leading up to it.

Event Data

The second argument to dregs.track() is a plain object of custom key-value pairs. Dregs stores this data with the event and displays it in the dashboard, giving you context about what happened.

Dregs reserves a few keys. Do not overwrite them:

• _u — the page URL (set automatically)
• _i — the identity ID (set automatically)
• _o — the organization (set automatically if configured)
• _e — error information (set automatically on failures)

Dregs treats any key starting with an underscore as a system field. Avoid underscore prefixes for your own data to prevent conflicts.

Privacy Considerations

Dregs automatically redacts underscore-prefixed fields from API responses, preventing inadvertent exposure of internal system data. For your own custom data, apply the same principle you would to any audit log: send only data you have a legitimate reason to process and that your users have consented to where required.

Event data is scoped to your account and never shared across customers. Only authenticated users on your team — or your own backend through API credentials — can access your event data.