Identifying users

Call datacub.identify(userId) after login and datacub.reset() at logout. The user's earlier activity on that browser or phone is linked to them.

After login or signup

async function login(email: string, password: string) {
  const user = await api.login(email, password)
  datacub.identify(user.id, { email: user.email, name: user.name })
  return user
}

Use your own stable internal user ID: the one in your database that never changes. Call identify again on every page load or app start while the user is signed in; with the same ID and no traits it sends nothing new.

Name, email and phone

Pass them as traits, so the Users page shows who a Registered user is and you can find them by email or phone:

datacub.identify('user_8f3a2c', {
  email: 'sara@example.sa',
  name: 'Sara Alqahtani',
  phone: '0551234567',
  plan: 'growth', // any other trait, under the same rules as event properties
})
  • Pass traits at login and when they change (a profile edit), not on every page load: each call with traits sends them again.
  • datacub tidies them on the server: emails are trimmed and lowercased, phones become international format (a Saudi 05 mobile becomes +9665...; other countries need their + code). A value that does not parse is dropped, never stored as typed.
  • They describe the user; they never identify them. Two users with the same email or phone stay two users.
  • Only these three keys may carry contact data. An email in any other trait or in a track() property is still redacted.

At logout

async function logout() {
  await api.logout()
  datacub.reset()
}

reset() starts a new Guest ID and session. Without it, the next person on a shared phone or computer is counted as the last user.

Workspaces and teams

If your users belong to a company, team or workspace, pass its ID too. It is stored with every event, so you can count active companies, not only people.

datacub.identify(user.id, { account: workspace.id })

IDs datacub refuses

So that no personal data becomes a key, identify refuses user IDs that look like an email address, a Saudi national or Iqama ID, a Saudi mobile or a phone number in international format, a card number or a JWT, and placeholders such as null, undefined, anonymous, guest or 0. The same rules apply to account. A refused call does nothing; on localhost the SDK says why in the console.

If your user IDs are emails or phone numbers, send a different stable ID from your database instead, and pass the email or phone as a trait.

How linking works

  • Before identify, the user is a Guest: a random ID kept in a first-party cookie (web) or app storage (mobile).
  • identify links that Guest's earlier activity to the user, who is now Registered.
  • The same user on a laptop and a phone: each device links when they sign in there with the same ID.
  • A different user signs in on the same device: the SDK resets first, so two people are never merged.
  • datacub never matches users by IP address, device traits, email or phone.

More in Guests and Registered users.

With consent first turned on, identify before datacub.consent.grant() is kept in memory and applied at grant. Nothing is stored or sent before that.

In React Native

The calls are the same:

import datacub from '@datacub/react-native'

datacub.identify('user_8f3a2c', { account: 'ws_51', email: 'sara@example.sa' })
// at logout
datacub.reset()