You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
7
9
8
10
<Callouttype="warn">
9
11
User identification processes personal data. Make sure you have a lawful
10
12
basis (typically consent), disclose it in your privacy policy, and only send
11
13
traits you are allowed to process.
12
14
</Callout>
13
15
14
-
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.
15
-
16
-
## How it works
17
-
18
-
- Every visitor has an anonymous ID stored on their device.
19
-
- When you call `identify(profileId, traits)`, the ID you pass is attached to every subsequent event and a profile is created for it.
20
-
- Events sent after `identify()` are attributed to that user, including earlier pageviews from the same session.
21
-
- The profile ID is stored in localStorage and survives reloads. Call `clearProfile()` on logout.
16
+
## Quick Start
22
17
23
-
<Callouttype="info">
24
-
Pass an opaque, stable ID from your database (max 128 characters, stored
25
-
verbatim) — not an email address. Emails belong in traits.
The same methods live on the global object once the script loads.
32
48
33
-
// On login or signup
34
-
identify(user.id, {
35
-
email: user.email,
36
-
name: user.name,
49
+
<CodeBlocklanguage="js">
50
+
{`// On login or signup
51
+
window.databuddy.identify("user_12345", {
52
+
email: "jo@acme.com",
53
+
name: "Jo Doe",
37
54
plan: "pro",
38
55
});
39
56
40
-
// Later, update traits without re-identifying
41
-
setTraits({ plan: "enterprise" });
42
-
43
57
// On logout
44
-
clearProfile();`}
58
+
window.databuddy.clearProfile();`}
45
59
</CodeBlock>
60
+
</Tab>
61
+
<Tabvalue="Node.js">
62
+
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.
46
63
47
-
Safe to call on every page load: repeat calls with the same ID and no traits are deduplicated to one request per session.
48
-
49
-
### Script tag
64
+
<CodeBlocklanguage="ts">
65
+
{`import { Databuddy } from "@databuddy/sdk/node";
50
66
51
-
If you use the script tag instead of the npm package, the same methods live on the global:
Pass an opaque, stable ID from your database (max 128 characters, stored
83
+
verbatim) — not an email address. Emails belong in traits.
84
+
</Callout>
85
+
86
+
## How It Works
87
+
88
+
- Every visitor has an anonymous ID stored on their device.
89
+
-`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.
90
+
- The profile ID persists in localStorage across reloads. Call `clearProfile()` on logout to return to anonymous tracking.
91
+
- Identified users appear on the **Users** page with their name and email, and collapse into one person across all their devices.
57
92
58
93
## Traits
59
94
@@ -68,70 +103,51 @@ Traits are flat key/value metadata about the user. Values must be strings, numbe
68
103
69
104
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.
70
105
71
-
Setting a trait to `null` removes it:
72
-
73
-
<CodeBlocklanguage="ts">
74
-
{`setTraits({ trial_ends_at: null });`}
75
-
</CodeBlock>
76
-
77
-
## Server-side (Node)
78
-
79
-
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:
106
+
Update traits later without re-identifying, and remove one by setting it to `null`:
80
107
81
108
<CodeBlocklanguage="ts">
82
-
{`import { Databuddy } from "@databuddy/sdk/node";
If you use the Stripe or Paddle integration, include the user ID in your payment metadata and transactions are attributed to the identified user:
105
117
118
+
<Tabsitems={['Stripe', 'Paddle']}>
119
+
<Tabvalue="Stripe">
106
120
<CodeBlocklanguage="ts">
107
-
{`// Stripe: metadata on the PaymentIntent
108
-
await stripe.paymentIntents.create({
121
+
{`await stripe.paymentIntents.create({
109
122
amount,
110
123
currency,
111
124
metadata: {
112
125
databuddy_profile_id: user.id,
113
-
databuddy_session_id: sessionId,
114
126
},
115
-
});
116
-
117
-
// Paddle: custom_data on the transaction
118
-
{ custom_data: { profile_id: user.id } }`}
127
+
});`}
128
+
</CodeBlock>
129
+
</Tab>
130
+
<Tabvalue="Paddle">
131
+
<CodeBlocklanguage="ts">
132
+
{`{ custom_data: { profile_id: user.id } }`}
119
133
</CodeBlock>
134
+
</Tab>
135
+
</Tabs>
120
136
121
-
## API reference
137
+
## API Reference
122
138
123
-
### identify(profileId, traits?)
139
+
### `identify(profileId, traits?)`
124
140
125
-
Links the browser to a user ID. Persists across sessions, attaches to every subsequent event.
141
+
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.
126
142
127
-
### setTraits(traits)
143
+
### `setTraits(traits)`
128
144
129
145
Merges traits into the identified user's profile. Requires a prior `identify()` — otherwise a no-op that warns in debug builds.
130
146
131
-
### clearProfile()
147
+
### `clearProfile()`
132
148
133
149
Forgets the identified user. The anonymous ID is kept, so subsequent activity is tracked anonymously again.
134
150
135
-
### getProfileId()
151
+
### `getProfileId()`
136
152
137
153
Returns the currently identified user ID, or `null` when anonymous.
0 commit comments