By default, Databuddy tracks visitors with an anonymous device ID. Calling identify() links that activity to a user ID from your own system, so the same person is recognized across sessions and devices — and your dashboard shows real names and emails instead of anonymous visitors.

User identification processes personal data. Make sure you have a lawful basis (typically consent), disclose it in your privacy policy, and only send traits you are allowed to process.

Quick Start

Call identify() when your auth state resolves — on every page load is fine, repeat calls are deduplicated to one request per session.

import { clearProfile, identify } from "@databuddy/sdk";

function IdentifyUser() {
const { data: session, isPending } = authClient.useSession();

useEffect(() => {
  if (isPending) {
    return;
  }
  if (session?.user) {
    identify(session.user.id, {
      email: session.user.email,
      name: session.user.name,
    });
  } else {
    clearProfile();
  }
}, [session, isPending]);

return null;
}

The same methods live on the global object once the script loads.

// On login or signup
window.databuddy.identify("user_12345", {
email: "jo@acme.com",
name: "Jo Doe",
plan: "pro",
});

// On logout
window.databuddy.clearProfile();

Backends can identify users with an API key that has the track:events scope for the target website. Pass the client's anonymous ID (readable in the browser via getAnonymousId()) to link the device's activity.

import { Databuddy } from "@databuddy/sdk/node";

const client = new Databuddy({
apiKey: process.env.DATABUDDY_API_KEY,
websiteId: "your-website-id",
});

await client.identify({
profileId: user.id,
anonymousId: cookies.get("did"),
traits: { email: user.email, plan: "pro" },
});

Pass an opaque, stable ID from your database (max 128 characters, stored verbatim) — not an email address. Emails belong in traits.

How It Works

Every visitor has an anonymous ID stored on their device.
identify(profileId, traits) links that ID to your user and attaches the user ID to every subsequent event, including earlier pageviews from the same session.
The profile ID persists in localStorage across reloads. Call clearProfile() on logout to return to anonymous tracking.
Identified users appear on the Users page with their name and email, and collapse into one person across all their devices.

Traits

Traits are flat key/value metadata about the user. Values must be strings, numbers, booleans, or null — nested objects are rejected. Limits: 50 keys, 2KB serialized.

Trait	Behavior
`username`	Primary display name in the dashboard
`name`	Fallback display name when `username` is absent
`email`	Shown under the user's name; lowercased
anything else	Stored on the profile and shown in the user detail view

Display names and emails are encrypted at rest (AES-256-GCM). Custom traits are stored as regular values so you can filter and segment by them.

Update traits later without re-identifying, and remove one by setting it to null:

import { setTraits } from "@databuddy/sdk";

setTraits({ plan: "enterprise", trial_ends_at: null });

Revenue Attribution

If you use the Stripe or Paddle integration, include the user ID in your payment metadata and transactions are attributed to the identified user:

await stripe.paymentIntents.create({
amount,
currency,
metadata: {
  databuddy_profile_id: user.id,
},
});

{ custom_data: { profile_id: user.id } }

API Reference

`identify(profileId, traits?)`

Links the browser to a user ID. Persists across sessions, attaches to every subsequent event. Safe to call on every page load — repeat calls with the same ID and no traits send one request per session.

`setTraits(traits)`

Merges traits into the identified user's profile. Requires a prior identify() — otherwise a no-op that warns in debug builds.

`clearProfile()`

Forgets the identified user. The anonymous ID is kept, so subsequent activity is tracked anonymously again.

`getProfileId()`

Returns the currently identified user ID, or null when anonymous.

Identify Users