Custom User Identification¶

The SDK generates an identifier for anonymous users. After users log in, you can call setUser() to write stable business user information, making it easier to query the Views, Actions, Resources, and Errors of the same user across Sessions.

It is recommended to provide at least id. Do not use frequently changing nicknames or email addresses in place of the stable user ID.

When using User Analysis to associate business users, you must pass a stable, non-empty id when first setting or switching the business user. The SDK's user.id corresponds to the userid field stored in the Explorer; the non-empty identifier automatically generated by the SDK can also participate in user statistics without requiring a name or email.

When multiple applications in the same Workspace need joint analysis, use consistent business ID rules to avoid the same ID corresponding to different users.

NPM Example¶

import { datafluxRum } from "@truewatchtech/browser-rum"

datafluxRum.setUser({
  id: "user-1234",
  name: "John Doe",
  email: "john@example.com",
  membership_level: "gold"
})

CDN Example¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.setUser({
    id: "user-1234",
    name: "John Doe",
    email: "john@example.com"
  })

window.DATAFLUX_RUM.onReady(function () {
  window.DATAFLUX_RUM.setUser({
    id: "user-1234",
    name: "John Doe",
    email: "john@example.com"
  })
})

Logout or Switching Users¶

setUser() and clearUser() only update the user context; they do not automatically end or create a new Session. Starting with SDK 3.3.6, after logging in or switching accounts, you can first set the complete business user information, then call startSession() to create a new Session boundary:

datafluxRum.setUser({ id: "user-5678", name: "Jane Doe" })
datafluxRum.startSession()

When logging out, clear the business user information first and then create a new Session, so that subsequent events are no longer associated with the original business user:

datafluxRum.clearUser()
datafluxRum.startSession()

For CDN integration, use the methods with the same names on window.DATAFLUX_RUM; for asynchronous loading, execute them inside the onReady callback.

If you only need to update the name or other attributes of the same user, use setUserProperty() for a partial update. Do not use setUser() without an id to overwrite the existing user context, and there is no need to call startSession() in this case:

datafluxRum.setUserProperty("name", "Jane Smith")

Page Refresh and Local Storage¶

By default, the user context is kept in the memory of the tab. After a refresh, the application should restore the login state and then set the user information. After enabling storeContextsToLocal, the user context can be restored after a refresh; on logout, you still need to call clearUser() to clear the persisted business user information.

When multiple applications on the same origin use local storage, use storeContextsKey to distinguish Workspaces, applications, and environments. Tabs on the same origin that use the same Key may sync user context; storage isolation of the business context does not equal Session isolation, so you need to verify session attribution in multi-account scenarios. For parameter descriptions, see Web Application Integration.

Notes¶

1. Do not write sensitive information such as passwords, access tokens, or ID card numbers.
2. User information only affects events generated after it is set; it does not modify already reported data.
3. After switching users, update the user information and the Session together to avoid data from two accounts falling into the same Session.

In User Analysis, sessions that contain multiple users or whose complete user attribution cannot be confirmed do not provide replay. Updating user information later does not correct the attribution of historical sessions.

Verification¶

After setting a user, trigger a page action, and confirm in the View or Action Explorer that userid matches the set user.id. After logging in, switching accounts, or logging out, update the user context in the order described above and call startSession(), then confirm that the session_id of new events has changed and is no longer associated with the original business user.

When updating the attributes of the same user only through setUserProperty(), confirm that both userid and session_id remain unchanged.