> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aient.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# @aient/otel-browser SDK reference

> Configuration options for @aient/otel-browser including publishable key, service name, release metadata, and exporter URL overrides for browser telemetry.

# @aient/otel-browser

`@aient/otel-browser` sends browser traces and logs to Aient using public OTLP HTTP endpoints. Use a publishable key and release metadata from your build environment.

For React or Next.js (client mount, `identify`/`clearUser`, and cleanup), see the [browser quickstart](../quickstart/browser).

## Configuration

| Option                | Meaning                                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------------------------- |
| `publishableKey`      | Aient environment publishable key safe for browser code                                                 |
| `serviceName`         | Frontend service name; match source map uploads                                                         |
| `installationId`      | Caller-owned application installation ID, emitted as a resource and untrusted baggage correlation field |
| `attributes`          | Static resource attributes fixed for the SDK lifetime                                                   |
| `contextAttributes`   | Initial mutable string context for future spans and outgoing baggage                                    |
| `release.environment` | Deployment environment slug                                                                             |
| `release.commit`      | Build commit SHA; match source map uploads                                                              |
| `release.branch`      | Build branch or ref for release correlation                                                             |
| `exporterUrl`         | Optional base endpoint override; the SDK appends `/v1/traces` and `/v1/logs`                            |
| `exporterHeaders`     | Optional custom exporter headers merged with Aient auth                                                 |
| `logs.exporterUrl`    | Optional logs-specific endpoint override                                                                |

The SDK sends OTLP HTTP JSON payloads. `http/protobuf` is not bundled; legacy protobuf config falls back to JSON.

Avoid high-cardinality span names and avoid attaching sensitive user input to attributes.

## Dynamic context

Call `sdk.setContextAttributes()` after a business, account, or workspace switch. The call synchronously replaces the whole snapshot; `null` or an empty object clears it. `sdk.getContextAttributes()` returns a clone.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
sdk.setContextAttributes({
  'business.id': 'business_123',
  'workspace.id': 'workspace_456',
})

// Clear on logout
sdk.setContextAttributes(null)
```

Future spans capture the current snapshot at span start; in-flight and ended spans are not changed retroactively. Outgoing Fetch/XHR baggage preserves unrelated entries and replaces SDK-owned keys. All `enduser.*` keys and `app.installation.id` are omitted from generic context.

Browser context and baggage are untrusted telemetry correlation data. Never use them for authorization; downstream services must derive identity and access from trusted server-side sessions or credentials.

## User context and baggage

Call `sdk.identify({ userId, pseudoId, email, role })` after sign-in to replace the complete user snapshot and tag future browser spans/logs. Call `sdk.clearUser()` on sign-out. `sdk.getIdentity()` returns a clone containing the installation plus current user fields. The legacy user-context methods remain aliases.

`app.installation.id`, `enduser.id`, and `enduser.pseudo.id` may propagate as W3C `baggage`. They are correlation hints, not authentication. Email and role do not propagate. Aient backends derive authenticated `enduser.id` from the verified server session and overwrite the browser value before downstream work.

Use a stable, non-reversible hash (for example, an HMAC of the user id with a server-side secret) for `pseudoId` so you can correlate sessions without exposing PII.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
sdk.identify({
  userId: 'user_123',          // untrusted baggage correlation
  pseudoId: 'pseudo_abc',      // untrusted baggage correlation
  email: 'user@example.com',   // local span attribute only
  role: 'admin',               // local span attribute only
})
```