Skip to main content

Consent & GDPR

TraceLog is a tracking library, not a compliance solution. You are responsible for obtaining user consent before initializing TraceLog. This page explains how to integrate TraceLog with your consent management flow.

Never call init() before obtaining user consent

TraceLog begins capturing events the moment init() is called. Initializing before consent violates GDPR, CCPA, and similar privacy regulations.

Wait for explicit user consent before initializing:

import { tracelog } from '@tracelog/lib';

// 1. Show your cookie/consent banner
const userConsent = await showConsentBanner(); // Your consent solution

if (userConsent.analytics) {
  // 2. User accepted -- initialize TraceLog
  await tracelog.init({
    integrations: {
      tracelog: { projectId: 'your-project-id' }
    }
  });
} else {
  // 3. User rejected -- do NOT initialize
  console.log('Analytics consent denied');
}

Wrong -- initializing before consent:

// DO NOT do this
await tracelog.init(); // Already tracking before asking!
if (userConsent.analytics) {
  // Too late -- events have already been captured
}

When a user revokes consent after initially accepting, stop tracking immediately:

function handleConsentRevoke() {
  tracelog.destroy();       // Stop tracking, remove all listeners
  localStorage.clear();    // Clear stored session data
}

Call this from your consent management UI whenever the user changes their preference to reject analytics.

Protecting Sensitive UI Elements​

Use the data-tlog-ignore attribute to exclude sensitive elements from tracking entirely. TraceLog will not capture clicks, scroll interactions, or any metadata from ignored elements or their children.

<div data-tlog-ignore>
  <input type="password" name="password">
  <input type="text" name="credit_card">
  <button>Submit Payment</button>
</div>

When to Use data-tlog-ignore​

  • Payment forms -- credit card inputs, billing addresses, CVV fields
  • Password inputs -- login forms, password reset, change password
  • Admin actions -- delete, ban, or privileged operations where even button text could leak context
  • Personal data forms -- SSN, national ID, medical information, tax IDs
<!-- Payment form -- completely ignored -->
<form data-tlog-ignore action="/checkout">
  <input type="text" name="card_number" placeholder="Card number">
  <input type="text" name="cvv" placeholder="CVV">
  <button>Pay Now</button>
</form>

<!-- Admin panel -- ignored -->
<button data-tlog-ignore>Delete All Users</button>

<!-- Public action -- tracked normally -->
<button>Subscribe to Newsletter</button>

Sensitive URL Parameters​

TraceLog automatically strips 14 sensitive query parameters from tracked URLs:

token, auth, key, session, reset, password, api_key, apikey, secret, access_token, refresh_token, verification, code, otp

Extending the Default List​

Add application-specific parameters via the sensitiveQueryParams config option:

await tracelog.init({
  sensitiveQueryParams: [
    'affiliate_id',
    'promo_code',
    'referral',
  ],
  integrations: {
    tracelog: { projectId: 'your-project-id' }
  }
});

// Before: https://example.com/checkout?token=abc123&promo_code=SAVE20
// After:  https://example.com/checkout (both params removed)

The custom list is merged with the defaults -- you do not need to repeat the built-in parameters.

For users who consent to essential tracking only, reduce the scope of data collection:

import { tracelog } from '@tracelog/lib';

const consent = getUserConsent(); // Your consent manager

if (consent.level === 'full') {
  // Full analytics consent
  await tracelog.init({
    samplingRate: 1.0,
    errorSampling: 1.0,
    integrations: {
      tracelog: { projectId: 'your-project-id' }
    }
  });
} else if (consent.level === 'essential') {
  // Essential only -- minimal tracking
  tracelog.setTransformer('beforeSend', (event) => {
    if ('type' in event && ['scroll', 'web_vitals'].includes(event.type)) {
      return null; // Drop non-essential events
    }
    return event;
  });

  await tracelog.init({
    samplingRate: 0.1,   // 10% sampling
    errorSampling: 0.5,  // 50% error sampling
    integrations: {
      custom: {
        collectApiUrl: 'https://api.example.com/collect'
      }
    }
  });
} else {
  // No consent -- do not initialize
}

Respecting Do Not Track​

Check the browser's Do Not Track setting before initializing:

if (navigator.doNotTrack === '1') {
  console.log('Do Not Track enabled -- skipping analytics');
} else {
  await tracelog.init({
    integrations: {
      tracelog: { projectId: 'your-project-id' }
    }
  });
}
info

The Do Not Track header is not legally binding in most jurisdictions, but respecting it demonstrates good faith toward user privacy.

Pre-Production Checklist​

Before deploying TraceLog to production, verify the following:

  • TraceLog is only initialized after the user grants analytics consent
  • tracelog.destroy() is called when the user revokes consent
  • Consent rejection prevents init() from being called at all

Sensitive Data​

  • All payment forms, password inputs, and admin UIs are marked with data-tlog-ignore
  • Custom events (tracelog.event()) do not include PII (emails, phone numbers, addresses)
  • Application-specific sensitive URL parameters are added to sensitiveQueryParams

Configuration​

  • sessionTimeout is appropriate for your use case (default: 15 minutes)
  • errorSampling is configured to reduce noise (recommended: 0.1 for production)
  • globalMetadata does not contain PII

Documentation​

  • Your privacy policy discloses the use of TraceLog and what data is collected
  • Your privacy notice discloses the use of TraceLog for analytics tracking
  • Data retention periods are documented (client-side: 2 hours, server-side: per your plan)