Skip to main content

​
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

FieldDescriptionExample
client.browserBrowser name"Chrome"
client.browserVersionBrowser version"120.0.0"
client.userAgentFull user agent string"Mozilla/5.0..."

​
Operating System

FieldDescriptionExample
client.osOperating system"macOS"
client.osVersionOS version"14.0"
client.deviceTypeDevice category"desktop"

​
Display

FieldDescriptionExample
client.screenWidthScreen width (px)1920
client.screenHeightScreen height (px)1080
client.viewportWidthViewport width (px)1440
client.viewportHeightViewport height (px)900
client.colorDepthColor depth (bits)24
client.pixelRatioDevice pixel ratio2

​
Hardware

FieldDescriptionExample
client.cpuCoresNumber of CPU cores8
client.deviceMemoryDevice memory (GB)16
client.touchSupportTouch capabilityfalse

​
Network

FieldDescriptionExample
client.connectionTypeConnection type"4g"
client.onlineOnline statustrue

​
Locale

FieldDescriptionExample
client.languagePrimary language"en-US"
client.languagesAll languages"en-US,en"
client.timezoneTimezone"America/New_York"
client.timezoneOffsetUTC offset (minutes)-300

​
Page Context

FieldDescriptionExample
client.urlCurrent URL"https://app.example.com/swap"
client.originPage origin"https://app.example.com"
client.pathnameURL pathname"/swap"
client.referrerReferrer URL"https://google.com"
client.documentVisibilityPage visibility"visible"

​
Privacy

FieldDescriptionExample
client.cookiesEnabledCookies allowedtrue
client.doNotTrackDNT preferencefalse

​
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 (CreateTrace). Subsequent updates don’t resend metadata, reducing payload size. 
const trace = client.trace({ name: 'MyTrace' })
  .addEvent('started');
// → CreateTrace includes full metadata

trace.addEvent('completed');
// → UpdateTrace 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()
});

​
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

Retry Logic

Handle network failures gracefully

TypeScript

Full type safety with the SDK