Customize TraceLog to fit your specific needs with these advanced options.

Session Management

Session Timeout

Control how long a user session stays active without interaction.

TraceLog.init({
  id: 'your-project-id',
  sessionTimeout: 300000 // 5 minutes
});

Default: 15 minutes (900000ms)
Minimum: 30 seconds (30000ms)
Maximum: 24 hours (86400000ms)

When a session expires, TraceLog automatically starts a new session for the next user interaction.

Global Metadata

Add consistent data to every event automatically.

TraceLog.init({
  id: 'your-project-id',
  globalMetadata: {
    appVersion: '2.1.0',
    environment: 'production',
    userType: 'premium',
    featureFlags: ['new-ui', 'beta-features']
  }
});

Use cases:

• App version tracking
• Environment identification
• User segmentation
• Feature flags
• A/B test variants

Important: Global metadata is added to every single event, so keep it concise and relevant.

Custom Scroll Tracking

Track scrolling in specific containers instead of the entire page.

TraceLog.init({
  id: 'your-project-id',
  
  // Single container
  scrollContainerSelectors: '.main-content',
  
  // Multiple containers
  scrollContainerSelectors: [
    '.main-content',
    '#sidebar',
    '.article-body',
    '[data-scroll-container]'
  ]
});

Default behavior: Tracks window scroll
With selectors: Tracks scroll within specified elements

Benefits:

• More accurate engagement metrics
• Focus on important content areas
• Reduce noise from irrelevant scrolling
• Better insights for single-page applications

Privacy & Security

Sensitive Query Parameters

Automatically remove sensitive data from URLs before tracking.

TraceLog.init({
  id: 'your-project-id',
  sensitiveQueryParams: [
    'token',
    'password', 
    'secret',
    'api_key',
    'auth',
    'session_id',
    'user_id'
  ]
});

What it does: Strips these parameters from URLs in all page view events.

Example:

• Original URL: https://app.com/dashboard?token=abc123&page=analytics
• Tracked URL: https://app.com/dashboard?page=analytics

HTTPS Enforcement

TraceLog.init({
  id: 'your-project-id',
  allowHttp: false // Default: false (HTTPS only)
});

Production (recommended):

TraceLog.init({
  id: 'your-project-id',
  allowHttp: false // HTTPS only
});

Development only:

TraceLog.init({
  id: 'your-project-id',
  allowHttp: true // Allow HTTP for localhost
});

Third-Party Integrations

Google Analytics 4

Automatically sync events with Google Analytics.

TraceLog.init({
  id: 'your-project-id',
  integrations: {
    googleAnalytics: {
      measurementId: 'G-XXXXXXXXXX'
    }
  }
});

What it does:

• Sends TraceLog custom events to GA4
• Maintains consistent event tracking across platforms
• No need to implement GA4 separately
• Automatic event name and parameter mapping

Requirements:

• Valid GA4 measurement ID
• GA4 property must be configured
• Works alongside existing GA4 implementations

Environment-Specific Setup

Organize configuration for different environments.

Development

TraceLog.init({
  id: 'your-dev-project-id',
  allowHttp: true, // Allow localhost
  globalMetadata: {
    environment: 'development'
  }
});

Staging

TraceLog.init({
  id: 'your-staging-project-id',
  globalMetadata: {
    environment: 'staging',
    build: process.env.BUILD_NUMBER
  }
});

Production

TraceLog.init({
  id: 'your-prod-project-id',
  globalMetadata: {
    environment: 'production',
    version: '1.2.0'
  }
});

Framework Integration

React

// In your App.js or index.js
import { TraceLog } from '@tracelog/client';
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    const initializeTraceLog = async () => {
      try {
        await TraceLog.init({
          id: 'your-project-id',
          globalMetadata: {
            framework: 'react',
            version: React.version
          }
        });
      } catch (error) {
        console.error('Failed to initialize TraceLog:', error);
      }
    };

    initializeTraceLog();

    // Cleanup on unmount
    return () => {
      TraceLog.destroy();
    };
  }, []);

  return <div>Your app</div>;
}

Vue.js

// In your main.js
import { TraceLog } from '@tracelog/client';
import { createApp } from 'vue';

const app = createApp(App);

const initTraceLog = async () => {
  try {
    await TraceLog.init({
      id: 'your-project-id',
      globalMetadata: {
        framework: 'vue',
        version: '3.x'
      }
    });
    app.mount('#app');
  } catch (error) {
    console.error('TraceLog initialization failed:', error);
    app.mount('#app'); // Continue without tracking
  }
};

initTraceLog();

Next.js

// In your _app.js
import { TraceLog } from '@tracelog/client';
import { useEffect } from 'react';

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    const initTraceLog = async () => {
      try {
        await TraceLog.init({
          id: 'your-project-id',
          globalMetadata: {
            framework: 'nextjs'
          }
        });
      } catch (error) {
        console.error('TraceLog initialization failed:', error);
      }
    };

    initTraceLog();
  }, []);

  return <Component {...pageProps} />;
}

export default MyApp;

Angular

// In your main.ts or app.component.ts
import { TraceLog } from '@tracelog/client';

const initTraceLog = async () => {
  try {
    await TraceLog.init({
      id: 'your-project-id',
      globalMetadata: {
        framework: 'angular'
      }
    });
  } catch (error) {
    console.error('TraceLog initialization failed:', error);
  }
};

initTraceLog();

Performance Optimization

TraceLog automatically handles performance optimizations:

• Event batching - Groups events for efficient network requests
• Queue management - Handles network failures and retries
• Data compression - Minimizes payload size
• Async processing - Non-blocking event processing
• Memory management - Efficient cleanup and garbage collection

No manual configuration needed - these work automatically.

Configuration Organization

Environment-based Config

// config/tracelog.js
const configs = {
  development: {
    id: 'dev-project-id',
    allowHttp: true,
    globalMetadata: { 
      environment: 'development',
      debug: true
    }
  },
  staging: {
    id: 'staging-project-id',
    globalMetadata: { 
      environment: 'staging'
    }
  },
  production: {
    id: 'prod-project-id',
    globalMetadata: { 
      environment: 'production'
    }
  }
};

export default configs[process.env.NODE_ENV];

// main.js
import tracelogConfig from './config/tracelog.js';
import { TraceLog } from '@tracelog/client';

await TraceLog.init(tracelogConfig);

Testing & Development

Browser Environment Check

// Only initialize in browser environments
if (typeof window !== 'undefined' && typeof document !== 'undefined') {
  await TraceLog.init({
    id: 'your-project-id'
  });
}

Error Boundaries

try {
  await TraceLog.init({
    id: 'your-project-id'
  });
  TraceLog.event('app_initialized');
} catch (error) {
  console.error('TraceLog initialization failed:', error);
  // App continues without tracking
}

Development Debugging

TraceLog automatically provides helpful console logs in development environments to help debug tracking issues.