SDK reference

Identify users

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

Pass the signed-in user to DatabuddyProvider, or null when signed out. The provider calls identify() when the user signs in or their traits change, and reset() when they sign out.

tsx
import { DatabuddyProvider } from "@databuddy/sdk/react";

function Providers({ children }: { children: React.ReactNode }) {
const { data: session, isPending } = authClient.useSession();
const user = session?.user;

return (
  <DatabuddyProvider
    user={
      user
        ? { id: user.id, traits: { email: user.email, name: user.name } }
        : null
    }
    userPending={isPending}
  >
    {children}
  </DatabuddyProvider>
);
}

To manage identity yourself, omit user and call identify() when your auth state resolves and reset() on logout. Calling identify() on every page load is fine: repeat calls are deduplicated to one request per session.

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

identify(session.user.id, {
email: session.user.email,
name: session.user.name,
});

// On logout
reset();

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 reset() on logout (or pass user={null} to the React provider) 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.

TraitBehavior
usernamePrimary display name in the dashboard
nameFallback display name when username is absent
emailShown under the user's name; lowercased
anything elseStored 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 by calling identify() again with the same ID, and remove one by setting it to null. With the React provider, change the user's traits instead.

ts
import { identify } from "@databuddy/sdk";

identify(user.id, { plan: "enterprise", trial_ends_at: null });

Accounts from email domains

Users identified with an email are grouped by their work email domain on the Accounts page, with no other setup. Everyone signing in with an @acme.com address becomes one account, with the company's public name, logo and industry when they can be looked up. Personal addresses (Gmail, Outlook and the like) and your own team's domain are left out.

To group users by your own workspaces or organizations instead, with plan and billing, see Accounts.

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:

ts
await stripe.paymentIntents.create({
amount,
currency,
metadata: {
  databuddy_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. Calling it again with traits merges them into the profile.

reset()

Forgets the identified user and starts new anonymous and session IDs, so subsequent activity is tracked anonymously as a new visitor. Call it on logout.

getIds()

Returns { anonymousId, sessionId, profileId }. profileId is the currently identified user ID, or null when anonymous.

How is this guide?