Custom Analytics SDK

A flexible, privacy-compliant analytics SDK for tracking user behavior, conversions, and marketing attribution. Built as an alternative to Google Analytics with full customization control.

Features

• 🎯 Advanced User Identification: Fingerprinting + cookies + localStorage
• 🔒 Privacy Compliant: GDPR/CCPA ready with consent management
• 📊 Comprehensive Tracking: Page views, clicks, conversions, purchases
• 🚀 Performance Optimized: Batched requests, async processing
• 📱 Cross-Platform: Works on web, mobile, and desktop
• 🛡️ Ad Blocker Resistant: Uses custom endpoints
• 📈 Marketing Attribution: Full UTM parameter support
• 🔧 Highly Configurable: Customize everything

Installation

npm install custom-analytics-sdk

Quick Start

ES6 Modules

import analytics from "custom-analytics-sdk";

// Initialize the SDK
analytics.init({
  endpoint: "https://your-api.com/analytics/events",
  debug: true,
});

// Track events
analytics.track("button_click", { button_name: "signup" });
analytics.trackPageView({ page_type: "landing" });
analytics.trackClick(element, { campaign: "signup" });

API Reference

Initialization

init(config?)

Initialize the analytics SDK with configuration options.

import analytics from "custom-analytics-sdk";

analytics.init({
  endpoint: "https://your-api.com/analytics/events",
  batchSize: 10,
  flushInterval: 5000,
  enableFingerprinting: true,
  respectDoNotTrack: true,
  debug: true,
  autoTrack: true,
});

Core Methods

track(eventName, properties?, options?)

Track any custom event with optional properties.

analytics.track("video_play", {
  video_title: "Product Demo",
  video_duration: 120,
  video_position: 0,
});

trackPageView(properties?)

Track page views (auto-tracked by default).

analytics.trackPageView({
  page_category: "product",
  user_type: "premium",
});

trackClick(element, properties?)

Track element clicks with automatic element data extraction.

document.querySelector("#cta-button").addEventListener("click", (e) => {
  analytics.trackClick(e.target, { campaign: "summer-sale" });
});

User Management

identify(userId, properties?)

Associate events with a specific user ID.

analytics.identify("user_12345", {
  email: "[email protected]",
  plan: "premium",
  signup_date: "2025-01-15",
});

reset()

Reset user session and generate new IDs.

// Call on logout
analytics.reset();

Utility Methods

flush()

Immediately send all queued events.

analytics.flush();

destroy()

Stop all tracking and cleanup resources.

analytics.destroy();

Properties

Access SDK properties and status:

// Check if initialized
if (analytics.isInitialized) {
  console.log("SDK is ready");
}

// Get user identifiers
console.log("Fingerprint ID:", analytics.fingerprintId);
console.log("User ID:", analytics.userId);
console.log("Session ID:", analytics.sessionId);

// Get current configuration
console.log("Config:", analytics.config);

Auto-Tracking Features

When autoTrack: true, the SDK automatically tracks:

• Page Views: On initial load and route changes
• Click Events: Buttons, links, and elements with data-track attribute
• Form Submissions: All form submit events

Custom Auto-Tracking

Add data-track attribute to any element:

<button data-track="signup-cta">Sign Up Now</button>
<a href="/pricing" data-track="pricing-link">View Pricing</a>

Privacy & Compliance

GDPR Compliance

The SDK automatically respects privacy settings and Do Not Track headers:

import analytics from "custom-analytics-sdk";

// Initialize with privacy-first settings
analytics.init({
  endpoint: "/analytics/events",
  respectDoNotTrack: true,
  enableFingerprinting: false, // Disable for stricter privacy
  cookieDuration: 30, // Limit cookie duration
  debug: true,
});

// Check if tracking is allowed
if (analytics.isInitialized) {
  analytics.track("page_view");
} else {
  console.log("Tracking blocked due to privacy settings");
}

Cookie Management

// The SDK uses cookies for user identification
// Configure cookie settings during initialization
analytics.init({
  cookieName: "custom_analytics_id", // Custom cookie name
  cookieDuration: 365, // Days to keep the cookie
  respectDoNotTrack: true, // Respect browser DNT header
  ...
});

Backend Integration

Expected API Format

Your backend should expect POST requests to the configured endpoint:

// POST /analytics/events
[
  {
    fingerprintId: "fp_db535991d396a731",
    userId: null,
    sessionId: "sess_1756805723800_grpksxw40",
    event: "click",
    properties: {
      tag_name: "button",
      id: "",
      class_name: "",
      text: "點我",
      data_track: null,
    },
    ctx: {
      viewport: "390x844",
      screen: "390x844",
      user_agent:
        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.5 Safari/605.1.15",
      language: "zh-TW",
      timezone: "Asia/Taipei",
      timestamp_local: "2025-09-02T09:36:34.083Z",
    },
    timestamp: 1756805794083,
    url: "http://localhost:3000/",
    utm: {
      source: null,
      medium: null,
      campaign: null,
      content: null,
      term: null,
    },
  },
];

License

MIT License - see LICENSE file for details.