Getting Started
Adding Dregs to your application resembles adding Google Analytics. Drop in a script tag, identify your users, track key events, and Dregs 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 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 before the closing </body> tag.
The queue pattern buffers calls to dregs() if the
script hasn't finished loading.
<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 loads the script
without blocking page rendering.
When the page loads, Dregs fingerprints the device and sends an initialization event. Nothing else is required 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 every
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 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.
When to call identify: Call it every time the user loads an authenticated page, not only once at login. This associates all events and device data with the identity across sessions.
Step 3: Track key events
Events are the behavioral data that power 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 — 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: signups, logins, purchases, content creation, form submissions, and any 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.
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: server-verified events add signals that the browser alone can't provide. See Events for 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 the following:
-
Events page —
dregs_initevents arrive as users visit your site, and your custom events as users interact. -
Identities page — Once 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 common cause is an incorrect public key or a missing allowed origin in your credential settings.
Allowed origins: You can restrict API credentials 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 begins scoring your users. Scores update continuously as new data arrives, usually within seconds.
From here, you can: