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

> Learn to set up user identification in web-tracing using userUuid and sdkUserUuid. Assign your app user ID and let the SDK auto-generate the unique identifier for every telemetry payload.

- Repository: [m-cheng-web/web-tracing](https://github.com/m-cheng-web/web-tracing)
- Tags: how-to-guide
- Published: 2026-03-06

---

**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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/options.ts)**:

```typescript
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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/exportMethods.ts)**.

### Using `setUserUuid()` After Initialization

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

```typescript
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:

```typescript
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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/exportMethods.ts)**:

```typescript
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:

```typescript
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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/base.ts)**, the `BaseInfo` class computes a reactive base object:

```typescript
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

```typescript
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

```typescript
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

```typescript
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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/options.ts)**.
- Every event payload includes both identifiers through the computed base object in **[`packages/core/src/lib/base.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/base.ts)**.
- Retrieval methods `getUserUuid()` and `getSDKUserUuid()` are available in **[`packages/core/src/lib/exportMethods.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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.