Getting Started
Adding Dregs to your application is similar to adding Google Analytics. Drop in a script tag, identify your users, track key events, and Dregs immediately starts fingerprinting devices and scoring identities. Most integrations take under an hour.
Prerequisites
Before you begin, you'll need:
- A Dregs account (sign up at dregs.com)
- At least one API credential (create one in the Settings section of your dashboard)
Each credential has a public key (starts with pk_) for use
in your frontend tracking script, and a secret key (starts with sk_)
for server-side API calls. Never expose your secret key in client-side code!
Step 1: Add the tracking script
Add the following snippet to every page of your application, ideally in the
<head> or just before the closing </body> tag.
The queue pattern ensures that calls to dregs() are buffered if the
script hasn't finished loading yet.
<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>
Replace pk_your_public_key_here with the public key from your
credential settings. The async attribute ensures the script loads
without blocking page rendering.
As soon as the page loads, Dregs fingerprints the device and sends an initialization event. You don't need to do anything else to start collecting device data.
Step 2: Identify your users
Dregs needs to know who is using the device. Call dregs.identify()
whenever you know the user's identity — after login, after signup, or on any
authenticated page load.
dregs.identify('user_12345', {
name: 'Jane Cooper',
email: 'jane@example.com',
plan: 'pro'
});The first argument is the user's unique identifier from your system — a user ID, username, or possibly even an email address. This becomes the identity's ID in Dregs, so use whatever is stable and unique in your application.
The second argument is an optional object of key-value pairs. Pass whatever you find useful: name, email, plan, company, role. Dregs uses this data for authenticity scoring and displays it in the dashboard for easy identification.
When to call identify: Call it every time the user loads an authenticated page, not just once at login. This ensures all events and device data are properly associated with the identity, even across sessions.
Step 3: Track key events
Events are the behavioral data that powers scoring. Track the actions that
matter most in your application using dregs.track().
// Track a form submission
dregs.track('form_submit', { form: 'contact' });
// Track a purchase
dregs.track('purchase', { plan: 'pro', amount: 49 });
// Track a plan upgrade
dregs.track('plan_upgrade', { from: 'free', to: 'pro' });
// Track a settings change
dregs.track('settings_change', { setting: 'notifications' });
The first argument is the event name — we recommend you use lowercase with underscores, like
form_submit or plan_upgrade. The second argument is an optional data object with any
additional context you want to capture.
You don't need to track everything. Focus on the events that distinguish good users from bad ones: signups, logins, purchases, content creation, form submissions, and any particular actions that abusers in your app tend to exploit.
Optional: Track backend events
The tracking script captures what happens in the browser, but your server often sees actions the frontend never touches — payment processing, API calls, background jobs, and administrative changes.
You can send these server-side events directly to the Dregs API using your credential's
secret key. Include the same user ID you pass to
dregs.identify(), and Dregs stitches frontend and backend events into a
single identity timeline.
POST https://dregs.com/api/events
Authorization: Bearer sk_your_secret_key
Content-Type: application/json
{
"type": "payment_received",
"data": { "amount": 49.99, "plan": "pro" },
"identity": {
"id": "user_12345",
"data": { "name": "Jane Cooper", "email": "jane@example.com" }
}
}Backend tracking is optional but valuable, because server-verified events add signals that the browser alone can't provide. See Events for the full details on setting up backend event tracking.
Step 4: Verify in the dashboard
After deploying the tracking script, open your Dregs dashboard and check:
-
Events page — You should see
dregs_initevents arriving as users visit your site, and your custom events as users interact. -
Identities page — After users trigger
identify(), their identities appear here with names and emails from the data you passed. - Devices page — Each unique browser/device combination appears with its fingerprint, IP address, and geolocation.
If events aren't arriving, check the browser console for errors. The most common issue is an incorrect public key or a missing allowed origin in your credential settings.
Allowed origins: Your API credentials can be restricted to specific domains. If you're testing
on localhost, make sure your credential's allowed origins include your development URL, or leave
the field empty to allow all origins during development.
What Happens Next
With the tracking script installed and events flowing, Dregs immediately begins scoring your users. Scores update continuously as new data arrives, typically within seconds.
From here, you can: