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

# Browser Metadata

> Automatic collection of browser environment data (Only supported for client web sdk)

## Overview

The SDK automatically collects rich browser metadata and includes it with your traces. This data helps you understand the environment where events occurred, debug issues, and analyze user patterns.

## Enabling Metadata Collection

Metadata collection is enabled by default. To disable it:

```typescript theme={null}
const trace = client.trace({
  name: 'MyTrace',
  includeUserMeta: false  // Disable metadata
});
```

## Collected Metadata

The SDK collects 27+ environment metrics, organized into categories:

### Browser Information

| Field                   | Description            | Example            |
| ----------------------- | ---------------------- | ------------------ |
| `client.browser`        | Browser name           | `"Chrome"`         |
| `client.browserVersion` | Browser version        | `"120.0.0"`        |
| `client.userAgent`      | Full user agent string | `"Mozilla/5.0..."` |

### Operating System

| Field               | Description      | Example     |
| ------------------- | ---------------- | ----------- |
| `client.os`         | Operating system | `"macOS"`   |
| `client.osVersion`  | OS version       | `"14.0"`    |
| `client.deviceType` | Device category  | `"desktop"` |

### Display

| Field                   | Description          | Example |
| ----------------------- | -------------------- | ------- |
| `client.screenWidth`    | Screen width (px)    | `1920`  |
| `client.screenHeight`   | Screen height (px)   | `1080`  |
| `client.viewportWidth`  | Viewport width (px)  | `1440`  |
| `client.viewportHeight` | Viewport height (px) | `900`   |
| `client.colorDepth`     | Color depth (bits)   | `24`    |
| `client.pixelRatio`     | Device pixel ratio   | `2`     |

### Hardware

| Field                 | Description         | Example |
| --------------------- | ------------------- | ------- |
| `client.cpuCores`     | Number of CPU cores | `8`     |
| `client.deviceMemory` | Device memory (GB)  | `16`    |
| `client.touchSupport` | Touch capability    | `false` |

### Network

| Field                   | Description     | Example |
| ----------------------- | --------------- | ------- |
| `client.connectionType` | Connection type | `"4g"`  |
| `client.online`         | Online status   | `true`  |

### Locale

| Field                   | Description          | Example              |
| ----------------------- | -------------------- | -------------------- |
| `client.language`       | Primary language     | `"en-US"`            |
| `client.languages`      | All languages        | `"en-US,en"`         |
| `client.timezone`       | Timezone             | `"America/New_York"` |
| `client.timezoneOffset` | UTC offset (minutes) | `-300`               |

### Page Context

| Field                       | Description     | Example                          |
| --------------------------- | --------------- | -------------------------------- |
| `client.url`                | Current URL     | `"https://app.example.com/swap"` |
| `client.origin`             | Page origin     | `"https://app.example.com"`      |
| `client.pathname`           | URL pathname    | `"/swap"`                        |
| `client.referrer`           | Referrer URL    | `"https://google.com"`           |
| `client.documentVisibility` | Page visibility | `"visible"`                      |

### Privacy

| Field                   | Description     | Example |
| ----------------------- | --------------- | ------- |
| `client.cookiesEnabled` | Cookies allowed | `true`  |
| `client.doNotTrack`     | DNT preference  | `false` |

## Using Metadata Utilities

The SDK exports utility functions for direct metadata access:

```typescript theme={null}
import {
  getClientMetadata,
  detectBrowser,
  detectOS,
  detectDeviceType
} from '@miradorlabs/web-sdk';

// Get all metadata
const metadata = getClientMetadata();
console.log(metadata);

// Individual detection functions
const browser = detectBrowser();  // { name: 'Chrome', version: '120.0.0' }
const os = detectOS();            // { name: 'macOS', version: '14.0' }
const device = detectDeviceType(); // 'desktop' | 'mobile' | 'tablet'
```

## When Metadata is Sent

Metadata is included only on the **first flush** (FlushTrace). Subsequent flushes don't resend metadata, reducing payload size.

```typescript theme={null}
const trace = client.trace({ name: 'MyTrace' })
  .addEvent('started');
// → First FlushTrace includes full metadata

trace.addEvent('completed');
// → Subsequent FlushTrace does NOT include metadata (already sent)
```

## IP Address

The client's IP address is **not** collected by the SDK. Instead, it's captured by the backend from request headers. This ensures accurate IP detection even when users are behind proxies.

## Privacy Considerations

### Selective Collection

If you have privacy requirements, disable automatic collection and add only what you need:

```typescript theme={null}
import { detectBrowser, detectOS } from '@miradorlabs/web-sdk';

const trace = client.trace({
  name: 'PrivacyAware',
  includeUserMeta: false  // Disable automatic collection
})
.addAttributes({
  // Only include what's necessary
  browser: detectBrowser().name,
  deviceType: detectDeviceType()
});
```

### GDPR Compliance

Metadata collection should be covered in your privacy policy. Consider:

* Informing users about data collection
* Providing opt-out mechanisms
* Respecting Do Not Track preferences

## Next Steps

<CardGroup cols={2}>
  <Card title="Retry Logic" icon="rotate" href="/advanced/retry-logic">
    Handle network failures gracefully
  </Card>

  <Card title="TypeScript" icon="code" href="/advanced/typescript">
    Full type safety with the SDK
  </Card>
</CardGroup>