Browser Metadata

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:

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:

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.

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:

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()
});

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

Retry Logic

Handle network failures gracefully

TypeScript

Full type safety with the SDK

Getting Started

Core Concepts

Web3 Integration

OpenTelemetry

Automations

AI & Agents

Advanced

Best Practices

Overview

Enabling Metadata Collection

Collected Metadata

Browser Information

Operating System

Display

Hardware

Network

Locale

Page Context

Privacy

Using Metadata Utilities

When Metadata is Sent

IP Address

Privacy Considerations

Selective Collection

Next Steps

Retry Logic

TypeScript

​Overview

​Enabling Metadata Collection

​Collected Metadata

​Browser Information

​Operating System

​Display

​Hardware

​Network

​Locale

​Page Context

​Privacy

​Using Metadata Utilities

​When Metadata is Sent

​IP Address

​Privacy Considerations

​Selective Collection

​GDPR Compliance

​Next Steps

Retry Logic

TypeScript

Overview

Enabling Metadata Collection

Collected Metadata

Browser Information

Operating System

Display

Hardware

Network

Locale

Page Context

Privacy

Using Metadata Utilities

When Metadata is Sent

IP Address

Privacy Considerations

Selective Collection

GDPR Compliance

Next Steps