How to Set Up User Identification Using `userUuid` and `sdkUserUuid` in Web-Tracing

Call setUserUuid(id) to assign your application's user ID, while the SDK automatically generates sdkUserUuid via FingerprintJS; both identifiers are stored in the global options object and automatically attached to every telemetry payload.

The web-tracing library implements a dual identification system that distinguishes between an application-provided identity and a browser-fingerprinted identity. This approach allows backend systems to correlate authenticated user sessions with stable device-level identifiers, even when users are not logged in. Understanding how to configure userUuid and leverage the automatically generated sdkUserUuid ensures complete observability across your distributed tracing infrastructure.

Understanding the Dual Identification System

Web-Tracing maintains two distinct user identifiers in the global runtime configuration. The separation enables flexible tracking strategies that combine business logic (who the user claims to be) with technical telemetry (which browser instance is generating events).

Application-Supplied userUuid

The userUuid represents an identity provided by your host application, typically corresponding to your backend's user database. This value is stored in the Options class defined in packages/core/src/lib/options.ts:

export class Options implements InternalOptions {
  userUuid = ''          // ← external ID supplied by the application
  sdkUserUuid = ''       // ← ID generated by the SDK
  // ...
}

You can set this identifier either during SDK initialization or dynamically after the user authenticates.

SDK-Generated sdkUserUuid

The sdkUserUuid is a persistent, per-browser identifier created automatically by the SDK using FingerprintJS. This value remains stable across sessions for the same device and browser combination, enabling anonymous user tracking before authentication. The generation logic resides in BaseInfo.initSdkUserUuid() within packages/core/src/lib/base.ts.

Setting the External User Identifier

To establish the application-level identity, use the public API methods exposed in packages/core/src/lib/exportMethods.ts.

Using setUserUuid() After Initialization

The primary method for updating the user identity post-initialization is setUserUuid():

import { setUserUuid } from 'web-tracing'

// After user login or identity confirmation
setUserUuid('c8f9e3a4-6b12-4d5e-8f9a-1234567890ab')

This helper validates the SDK state before updating options.value.userUuid, ensuring the operation only executes when the tracing system is active.

Passing userUuid During Initialization

Alternatively, provide the identifier immediately when configuring the SDK:

import { initOptions } from 'web-tracing'

initOptions({
  dsn: 'https://your-server.com/collect',
  appName: 'e-commerce-app',
  userUuid: 'pre-known-user-id'  // Optional: set immediately
})

Retrieving User Identifiers

Access both identifiers programmatically using the getter methods defined in packages/core/src/lib/exportMethods.ts:

import { getUserUuid, getSDKUserUuid } from 'web-tracing'

// Returns the application-supplied ID (or empty string if not set)
const externalId = getUserUuid()

// Returns the FingerprintJS-generated browser ID
const browserId = getSDKUserUuid()

Both methods perform runtime validation via validateMethods() before returning the stored values from the reactive options object.

How the SDK Generates sdkUserUuid

During SDK initialization, the BaseInfo class executes initSdkUserUuid() to create the browser fingerprint. This asynchronous process uses FingerprintJS to generate a stable visitor ID:

private initSdkUserUuid() {
  return isTestEnv
    ? Promise.resolve().then(() => {
        this.sdkUserUuid = 'unit-test-id'
        options.value.sdkUserUuid = 'unit-test-id'
      })
    : load({})
        .then((fp: any) => fp.get())
        .then((result: any) => {
          const visitorId = result.visitorId
          this.sdkUserUuid = visitorId
          options.value.sdkUserUuid = visitorId
        })
}

In production environments, load({}) initializes the FingerprintJS agent, and the resulting visitorId is stored in both the local class property and the global options.value.sdkUserUuid. In test environments, the method resolves to a static 'unit-test-id' to ensure deterministic behavior.

Automatic Inclusion in Event Payloads

Both identifiers are automatically merged into the base payload that every telemetry event inherits. In packages/core/src/lib/base.ts, the BaseInfo class computes a reactive base object:

this.base = computed<Base>(() => ({
  ...this.device!,
  userUuid: options.value.userUuid,
  sdkUserUuid: this.sdkUserUuid,
  // ... additional metadata
}))

Consequently, every page view, error report, performance metric, and custom event transmitted to your collector includes both userUuid and sdkUserUuid, enabling server-side correlation of authenticated sessions with device fingerprints.

Practical Implementation Examples

Basic Setup in a Vanilla JavaScript Application

import { initOptions, setUserUuid, getUserUuid, getSDKUserUuid } from 'web-tracing'

// Initialize the SDK with mandatory configuration
initOptions({
  dsn: 'https://collector.example.com/api',
  appName: 'my-app',
  appCode: '001',
  appVersion: '1.0.0'
})

// Set the user identity after authentication
setUserUuid('user-12345')

// Access identifiers for debugging or UI display
console.log('Business ID:', getUserUuid())
console.log('Device Fingerprint:', getSDKUserUuid())

React Hook for Accessing Identifiers

import { useEffect } from 'react'
import { getBaseInfo } from 'web-tracing'

export function useUserIds() {
  useEffect(() => {
    const base = getBaseInfo()
    if (base) {
      console.log('Telemetry payload contains:')
      console.log(' → userUuid:', base.userUuid)
      console.log(' → sdkUserUuid:', base.sdkUserUuid)
    }
  }, [])
}

Updating Identity After Login Events

import { setUserUuid } from 'web-tracing'

async function handleLogin(credentials) {
  const response = await fetch('/api/login', {
    method: 'POST',
    body: JSON.stringify(credentials)
  })
  const user = await response.json()
  
  // Update tracing context with authenticated identity
  setUserUuid(user.uuid)
  
  // All subsequent events automatically include the new userUuid
}

Summary

• userUuid is set via setUserUuid() or initOptions(), representing your application's business identity.
• sdkUserUuid is generated automatically by BaseInfo.initSdkUserUuid() using FingerprintJS, providing a stable per-browser identifier.
• Both values are stored in the reactive Options instance defined in packages/core/src/lib/options.ts.
• Every event payload includes both identifiers through the computed base object in packages/core/src/lib/base.ts.
• Retrieval methods getUserUuid() and getSDKUserUuid() are available in packages/core/src/lib/exportMethods.ts.

Frequently Asked Questions

What is the difference between userUuid and sdkUserUuid?

userUuid represents an identity supplied by your application (such as a database primary key), while sdkUserUuid is a cryptographic fingerprint generated by FingerprintJS that identifies the specific browser and device combination. Use userUuid to correlate events with your user management system, and sdkUserUuid to track anonymous or unauthenticated sessions.

When should I call setUserUuid?

Call setUserUuid() immediately after the user authenticates or when your application obtains a stable user identifier. If the user ID is known at page load, you can alternatively pass it directly to initOptions({ userUuid: 'id' }) during SDK initialization.

Is sdkUserUuid persistent across browser sessions?

Yes. The sdkUserUuid generated by FingerprintJS remains consistent for the same browser, device, and user agent configuration across multiple sessions, unless the user clears browser storage or switches to a different device. This persistence enables longitudinal analysis of user behavior prior to authentication.

Can I retrieve these identifiers for custom logging purposes?

Yes. Use getUserUuid() and getSDKUserUuid() from packages/core/src/lib/exportMethods.ts to access the current values programmatically. Alternatively, call getBaseInfo() to retrieve the entire base payload object containing both identifiers along with device metadata.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}