Skip to main content

User Identification

The SDK provides a setUser method to associate analytics events with a known user. Once called, B2Metric links all subsequent events from that device to the user's profile in the dashboard, enabling per-user analytics, cohort analysis, and personalised campaign targeting.

6.1 Identify a User​

Call setUser once the user's identity is known — typically after login or session restore. The userId field is required; all other fields are optional but recommended.

B2Metric.setUser({
  userId: 'user_123',
  name: 'Ahmet',
  email: 'ahmet@example.com',
  plan: 'premium', // any custom attribute
})

6.2 What setUser Does​

Calling setUser performs two operations simultaneously:

  1. Sends a user_identify event to B2Metric. This creates or updates the user's profile in the dashboard — name, email, and any custom fields you pass are reflected immediately.
  2. Merges the supplied attributes into the user_properties of every subsequent event. Events logged after setUser carry the user context at the event level, which enables event-level filtering and segmentation.
Note

The user_properties snapshot attached to each event is taken at the moment the event is tracked. Calling setUser later does not retroactively update already-queued events. If a user attribute changes (for example, the user upgrades their plan), call setUser again with the updated values.

6.3 Supported Fields​

userId (string, required) — Your application's own identifier for the user. Use a stable value such as a database primary key or UUID. Do not use email addresses as the primary identifier since they can change.

name (string, optional) — The user's display name or first name.

surname (string, optional) — The user's surname or family name.

email (string, optional) — The user's email address.

Any additional key-value pair is accepted as a custom attribute. Custom values follow the same type rules as event properties: string, number, boolean, Date, plain objects, and arrays are all supported.

6.4 Device Fields Cannot Be Overridden​

If a key in the user object matches a device property collected automatically by the SDK (for example device_id or os_version), the device value always wins. This prevents accidental corruption of platform metadata.

6.5 Persistence Across App Launches​

User attributes are not persisted to disk between app launches. Call setUser again each time the app starts, once the user's identity is available (typically after a successful login check or session restore). A common pattern is to chain it after B2Metric.init resolves:

useEffect(() => {
  B2Metric.init({ apiKey: '...', appIdentifier: '...' })
    .then(() => {
      if (currentUser) {
        B2Metric.setUser({
          userId: currentUser.id,
          email: currentUser.email,
        })
      }
    })
}, [])