Browser SDK

Lightweight JavaScript SDK for event tracking and monitoring in web applications. Built on top of logstyx-js-core, the Browser SDK provides automatic DOM event tracking, error capture, and device information collection with zero dependencies.

Installation

Download the latest release from the GitHub releases page and add it to your HTML:

<!-- Configure before loading the script -->
<script>
  window.LogstyxConfig = {
    projectId: "your_project_id",
    endpoint: "https://your-domain.com/api/v1/logs"
  };
</script>

<!-- Load the SDK -->
<script src="logstyx-browser.min.js"></script>

Origin Configuration Required

Make sure to add your domain to the allowed origins in your Logstyx dashboard under Project Settings → Security.

Quick Start

Basic Setup

<script>
  window.LogstyxConfig = {
    projectId: "proj_abc123",
    endpoint: "https://logs.yourcompany.com/api/v1/logs"
  };
</script>
<script src="logstyx-browser.min.js"></script>

<!-- Track button clicks automatically -->
<button data-logstyx-event="click">
  Track This Click
</button>

With Automatic Tracking

<script>
  window.LogstyxConfig = {
    projectId: "proj_abc123",
    endpoint: "https://logs.yourcompany.com/api/v1/logs",
    captureUncaught: true,  // Auto-capture JavaScript errors
    tracker: {
      events: ['click', 'submit'],  // Track all clicks and form submissions
      context: ['event', 'url', 'pageTitle'],
      data: ['tag', 'id', 'class', 'text']
    }
  };
</script>
<script src="logstyx-browser.min.js"></script>

Configuration

Required Options

projectId (string)

Your Logstyx project identifier.

projectId: "proj_abc123xyz"

endpoint (string)

Your Logstyx API endpoint.

endpoint: "https://logs.yourcompany.com/api/v1/logs"

Optional Options

captureUncaught (boolean)

Automatically capture uncaught JavaScript exceptions.

Default: false

captureUncaught: true

When enabled, all uncaught errors are logged as critical:

// This error will be automatically captured
throw new Error('Something went wrong');

captureUnhandledRejections (boolean)

Automatically capture unhandled Promise rejections.

Default: false

captureUnhandledRejections: true

When enabled, unhandled promise rejections are logged as critical:

// This rejection will be automatically captured
Promise.reject(new Error('Async operation failed'));

persistentSession (boolean)

Automatically add sessionId on context that persist over the visiting session.

Default: false

persistentSession: true

tracker (object)

Configuration for automatic DOM event tracking.

tracker: {
  events: ['click', 'submit', 'change'],
  context: ['event', 'url', 'referrer', 'pageTitle'],
  data: ['tag', 'id', 'class', 'text'],
  selector: ['a', 'button', 'form']
}

Tracker Options:

Option	Type	Description
events	string[]	DOM events to track (e.g., 'click', 'submit', 'change', 'focus')
context	string[]	Context fields: 'event', 'url', 'referrer', 'pageTitle'
data	string[]	Element attributes: 'tag', 'id', 'class', 'text'
selector	string[]	CSS selectors to monitor. Empty = track all elements

Tracking Behavior:

• If selector is empty or not set: Tracks all elements for configured events
• If selector is specified: Only tracks matching elements (unless they have data-logstyx-event)
• Elements with data-logstyx-event: Always tracked regardless of selector
• Elements with data-logstyx-skip="true": Never tracked

Data Attributes

Add tracking to specific HTML elements using data-logstyx-* attributes:

data-logstyx-event

Specify which DOM event(s) to track. Use space-separated values for multiple events.

<!-- Single event -->
<button data-logstyx-event="click">
  Click Me
</button>

<!-- Multiple events -->
<input 
  type="text" 
  data-logstyx-event="focus blur change"
  placeholder="Email">

data-logstyx-context

Add context metadata as a JSON object. Must use double quotes for valid JSON.

<button 
  data-logstyx-event="click"
  data-logstyx-context='{"feature":"export", "format":"pdf"}'>
  Export PDF
</button>

data-logstyx-payload

Add event-specific data as a JSON object.

<button 
  data-logstyx-event="click"
  data-logstyx-payload='{"amount":99.99, "currency":"USD"}'>
  Complete Purchase
</button>

data-logstyx-level

Set log severity level.

Default: "info"

Options: "info", "warning", "error", "critical"

<button 
  data-logstyx-event="click"
  data-logstyx-level="warning">
  Delete Account
</button>

data-logstyx-skip

Exclude an element from tracking.

<!-- This button will NOT be tracked -->
<button data-logstyx-skip="true">
  Don't Track Me
</button>

Automatic Device Information

The Browser SDK automatically collects and includes device information with every event:

{
  type: "browser",
  origin: "https://example.com",
  os: "Windows",           // or MacOS, Linux, Android, iOS, Unknown
  browser: "Chrome",       // or Edge, Firefox, Safari, Unknown
  screen: "1920x1080",
  platform: null
}

This information helps you understand which browsers and devices your users are on.

Context Fields

When included in tracker.context, these fields are automatically populated:

event

The DOM event type that triggered the log.

context: {
  event: "click"  // or "submit", "change", etc.
}

url

Current page URL.

context: {
  url: "https://example.com/pricing"
}

referrer

Previous page URL (or null if none).

context: {
  referrer: "https://google.com"
}

pageTitle

Page title (or null if none).

context: {
  pageTitle: "Pricing - Example App"
}

Fallback Payload

When an element doesn't have data-logstyx-payload, the SDK creates a fallback payload based on tracker.data:

tag

Element tag name in uppercase.

<button>Click Me</button>
<!-- Payload: { tag: "BUTTON" } -->

id

Element ID if present.

<button id="submit-btn">Submit</button>
<!-- Payload: { tag: "BUTTON", id: "submit-btn" } -->

class

Element class names if present.

<button class="btn btn-primary">Submit</button>
<!-- Payload: { tag: "BUTTON", class: "btn btn-primary" } -->

text

First 100 characters of element text content.

<button>Complete Your Purchase</button>
<!-- Payload: { tag: "BUTTON", text: "Complete Your Purchase" } -->

Examples

Track All Button Clicks

<script>
  window.LogstyxConfig = {
    projectId: "proj_abc123",
    endpoint: "https://logs.example.com/api/v1/logs",
    tracker: {
      events: ['click'],
      context: ['event', 'url'],
      data: ['tag', 'id', 'text'],
      selector: ['button']  // Only track button clicks
    }
  };
</script>
<script src="logstyx-browser.min.js"></script>

<button>Track This</button>
<button id="cta">And This</button>

Track Form Submissions

<script>
  window.LogstyxConfig = {
    projectId: "proj_abc123",
    endpoint: "https://logs.example.com/api/v1/logs",
    tracker: {
      events: ['submit'],
      context: ['event', 'url', 'pageTitle'],
      selector: ['form']
    }
  };
</script>

<form data-logstyx-context='{"form":"newsletter"}'>
  <input type="email" name="email" required>
  <button type="submit">Subscribe</button>
</form>

Track Specific Links with Custom Data

<a 
  href="/pricing" 
  data-logstyx-event="click"
  data-logstyx-context='{"section":"navbar", "cta":"pricing"}'
  data-logstyx-level="info">
  View Pricing
</a>

<a 
  href="/signup" 
  data-logstyx-event="click"
  data-logstyx-context='{"section":"hero", "cta":"signup"}'
  data-logstyx-payload='{"plan":"pro", "trial":true}'
  data-logstyx-level="info">
  Start Free Trial
</a>

E-commerce Tracking

<!-- Add to cart button -->
<button 
  data-logstyx-event="click"
  data-logstyx-context='{"action":"add_to_cart"}'
  data-logstyx-payload='{"productId":"prod_123", "price":29.99, "quantity":1}'>
  Add to Cart
</button>

<!-- Checkout button -->
<button 
  data-logstyx-event="click"
  data-logstyx-context='{"action":"checkout"}'
  data-logstyx-payload='{"cartTotal":89.97, "itemCount":3}'>
  Proceed to Checkout
</button>

Feature Usage Tracking

<!-- Export button -->
<button 
  data-logstyx-event="click"
  data-logstyx-context='{"feature":"export"}'
  data-logstyx-payload='{"format":"csv", "rows":150}'>
  Export to CSV
</button>

<!-- Filter interaction -->
<select 
  data-logstyx-event="change"
  data-logstyx-context='{"feature":"filter"}'
  data-logstyx-payload='{"filterType":"category"}'>
  <option>All</option>
  <option>Active</option>
  <option>Archived</option>
</select>

Error Capture

<script>
  window.LogstyxConfig = {
    projectId: "proj_abc123",
    endpoint: "https://logs.example.com/api/v1/logs",
    captureUncaught: true,
    captureUnhandledRejections: true
  };
</script>
<script src="logstyx-browser.min.js"></script>

<!-- All uncaught errors and promise rejections will be logged -->
<script>
  // This error will be automatically captured
  function riskyOperation() {
    throw new Error('Something went wrong');
  }
  
  // This rejection will be automatically captured
  async function asyncOperation() {
    throw new Error('Async error');
  }
</script>

Skip Tracking on Specific Elements

<script>
  window.LogstyxConfig = {
    projectId: "proj_abc123",
    endpoint: "https://logs.example.com/api/v1/logs",
    tracker: {
      events: ['click'],
      selector: ['button']  // Track all buttons
    }
  };
</script>

<!-- These will be tracked -->
<button>Track Me</button>
<button>Me Too</button>

<!-- This will NOT be tracked -->
<button data-logstyx-skip="true">Don't Track Me</button>

Multiple Events on One Element

<input 
  type="text"
  data-logstyx-event="focus blur change"
  data-logstyx-context='{"field":"email", "form":"signup"}'
  data-logstyx-level="info"
  placeholder="Enter your email">

<!-- Logs on:
  - focus: { event: "focus", field: "email", form: "signup" }
  - blur: { event: "blur", field: "email", form: "signup" }
  - change: { event: "change", field: "email", form: "signup" }
-->

Best Practices

1. Use Structured Context

Add meaningful context to understand user behavior:

<!-- ❌ Avoid: No context -->
<button data-logstyx-event="click">Buy Now</button>

<!-- ✅ Better: With context -->
<button 
  data-logstyx-event="click"
  data-logstyx-context='{"page":"pricing", "plan":"pro", "position":"hero"}'>
  Buy Now
</button>

2. Track Key User Actions

Focus on actions that matter for your business:

<!-- Sign-up CTA -->
<button 
  data-logstyx-event="click"
  data-logstyx-context='{"action":"signup", "source":"landing-page"}'>
  Get Started
</button>

<!-- Feature activation -->
<button 
  data-logstyx-event="click"
  data-logstyx-context='{"feature":"api", "action":"enable"}'>
  Enable API Access
</button>

3. Use Appropriate Log Levels

<!-- Info: Normal user actions -->
<button 
  data-logstyx-event="click"
  data-logstyx-level="info">
  View Details
</button>

<!-- Warning: Potentially risky actions -->
<button 
  data-logstyx-event="click"
  data-logstyx-level="warning">
  Delete Draft
</button>

<!-- Critical: Destructive actions -->
<button 
  data-logstyx-event="click"
  data-logstyx-level="critical">
  Delete Account
</button>

4. Enable Error Capture in Production

<script>
  window.LogstyxConfig = {
    projectId: "proj_abc123",
    endpoint: "https://logs.example.com/api/v1/logs",
    
    // Enable in production
    captureUncaught: location.hostname !== 'localhost',
    captureUnhandledRejections: location.hostname !== 'localhost'
  };
</script>

5. Track Conversions and Goals

<!-- Purchase completion -->
<div 
  id="purchase-success"
  data-logstyx-event="load"
  data-logstyx-context='{"goal":"purchase_complete"}'
  data-logstyx-payload='{"orderId":"ord_123", "amount":149.99}'>
  Thank you for your purchase!
</div>

<!-- Newsletter signup -->
<form 
  data-logstyx-event="submit"
  data-logstyx-context='{"goal":"newsletter_signup", "source":"footer"}'>
  <!-- form fields -->
</form>

6. Respect User Privacy

Never track sensitive information:

<!-- ❌ Never track passwords, credit cards, or PII -->
<input 
  type="password" 
  data-logstyx-skip="true"
  name="password">

<input 
  type="text" 
  data-logstyx-skip="true"
  name="creditCard">

<!-- ✅ Track form submission, but not field values -->
<form data-logstyx-event="submit">
  <input type="password" name="password">
  <button type="submit">Login</button>
</form>

Troubleshooting

Events Not Being Tracked

Check origin configuration:

• Ensure your domain is added to allowed origins in Logstyx dashboard
• Check browser console for CORS errors

Verify configuration:

// Check if config is loaded
console.log(window.LogstyxConfig);

// Check if tracker is configured
console.log(window.LogstyxConfig.tracker);

Data Attributes Not Working

Ensure valid JSON:

<!-- ❌ Wrong: Single quotes inside -->
<button data-logstyx-context="{'key':'value'}">

<!-- ✅ Correct: Double quotes -->
<button data-logstyx-context='{"key":"value"}'>

Check attribute spelling:

<!-- ❌ Wrong spelling -->
<button data-logstix-event="click">

<!-- ✅ Correct spelling -->
<button data-logstyx-event="click">

Script Not Loading

Check file path:

<!-- Ensure the file exists at this path -->
<script src="logstyx-browser.min.js"></script>

<!-- Or use absolute path -->
<script src="/js/logstyx-browser.min.js"></script>

Check for JavaScript errors:

• Open browser console (F12)
• Look for error messages
• Ensure config is set before script loads

Nothing Is Being Logged

Verify endpoint:

// Test if endpoint is reachable
fetch(window.LogstyxConfig.endpoint, { method: 'OPTIONS' })
  .then(() => console.log('Endpoint reachable'))
  .catch(err => console.error('Endpoint error:', err));

Check project ID:

• Verify projectId matches your Logstyx dashboard
• Ensure no typos in the ID