WaveTrace Client

A lightweight, TypeScript-first web analytics client for tracking user behavior, page views, clicks, and custom events. The primary goal for this client is to provide analytics on a specific user by tracking his/her activity on a DApp. Some tracking are automated while some could be manually tracked.

So, it provides:

• Both automated and manual tracking for users
• Connect annoymous/signed out user tracking linked to existing/future wallet/user login

Features

• Lightweight: Only 4.8KB minified
• TypeScript Support: Full type definitions included
• Zero Dependencies: No external dependencies
• DApp Ready: Built-in wallet tracking for Web3 applications
• Auto-Detect Wallets: Automatically detect and track MetaMask, Coinbase, and other wallet connections
• Transaction Tracking: Complete lifecycle tracking for blockchain transactions (initiated → pending → executed/failed)
• Offline Queue: localStorage persistence - events are saved and sent when back online
• Retry Logic: Exponential backoff for failed requests with configurable retries
• Smart Click Tracking: Intelligent filtering - track only buttons, links, and important interactions
• Automatic Tracking: Auto-track page views and clicks with configurable modes
• Event Batching: Efficient event batching with configurable batch size and timeout
• User Identification: Track user ID, username, wallet addresses, and custom properties
• Anonymous-to-Wallet Linking: Seamlessly connect anonymous activity to wallet addresses
• Session Management: Automatic session tracking with 30-minute timeout
• Privacy-Conscious: Configurable data collection
• Multiple Formats: ESM, CommonJS, and browser IIFE builds

Installation

npm install @wavetrace/client

Usage

Basic Setup (Browser)

<script src="https://unpkg.com/@wavetrace/client/dist/wavetrace.min.js"></script>
<script>
  const tracker = new WaveTrace.WaveTracker({
    endpoint: "https://your-api.com/track",
    autoTrackPageViews: true,
    autoTrackClicks: true,
  });
</script>

ES Modules

import { WaveTracker } from "@wavetrace/client";

const tracker = new WaveTracker({
  endpoint: "https://your-api.com/track",
  autoTrackPageViews: true,
  autoTrackClicks: true,
  batchSize: 10,
  batchTimeout: 5000,
  debug: false,
});

DApp Wallet Tracking

For Web3/DApp applications, track wallet connections with automatic detection or manual tracking:

Automatic Wallet Detection (Recommended)

const tracker = new WaveTracker({
  endpoint: "https://your-api.com/track",
  autoDetectWallet: true, // Automatically detect wallet connections
  autoTrackPageViews: true,
});

// That's it! Wallet connections are automatically tracked
// No need to manually call connectWallet() or disconnectWallet()

The tracker automatically:

• Detects when users connect wallets (MetaMask, Coinbase, etc.)
• Tracks wallet_connected event with wallet address and chain ID
• Links anonymous activity to wallet address
• Detects account switches
• Detects disconnections
• Handles network changes

Manual Wallet Tracking

// When user connects wallet (if not using auto-detection)
await tracker.connectWallet("0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", {
  properties: {
    chainId: 1,
    walletType: "metamask",
  },
});

// Track DApp events
tracker.track("swap_executed", {
  fromToken: "ETH",
  toToken: "USDC",
  amount: "1.5",
  txHash: "0x...",
});

// When user disconnects
await tracker.disconnectWallet();

How it works:

1. User browses your DApp anonymously → tracked with anonymous ID
2. User connects wallet → automatically linked to wallet address
3. All future events include wallet address
4. Backend receives wallet_connected event with previousAnonymousId for user merging

See DAPP-INTEGRATION.md for complete DApp integration guide.

Smart Click Tracking

WaveTrace includes intelligent click filtering to reduce noise and focus on meaningful interactions.

Default behavior (tracks only important elements):

const tracker = new WaveTracker({
  endpoint: "...",
  autoTrackClicks: true, // Uses 'important' mode - tracks buttons, links, data-track elements
});

Track specific elements with data-track:

<button data-track="connect-wallet">Connect Wallet</button>
<button data-track="execute-swap">Swap</button>
<div data-track="feature-card">
  <!-- Entire card is trackable -->
</div>

Advanced configuration:

const tracker = new WaveTracker({
  endpoint: "...",
  autoTrackClicks: {
    mode: "important", // 'all' | 'important' | 'data-attribute' | 'custom'
    ignoreSelectors: ["[data-track-ignore]", ".no-track"],
    customSelectors: [".my-button", "[data-action]"], // For 'custom' mode
  },
});

Tracking modes:

• important (default): Buttons, links, and data-track elements
• all: Every click on the page
• data-attribute: Only elements with data-track
• custom: Use your own CSS selectors

See CLICK-TRACKING.md for complete guide and examples.

User Identification

Track user information with your events:

tracker.identify({
  userId: "12345",
  username: "john_doe",
  wallet: "0x1234567890abcdef",
  email: "[email protected]",
  properties: {
    plan: "premium",
    signupDate: "2024-01-01",
  },
});

Transaction Tracking (DApps)

Automatically track the complete lifecycle of blockchain transactions:

// Track a swap transaction with automatic lifecycle tracking
const tx = await tracker.trackTransaction(
  "swap",
  async () => {
    // Your transaction logic
    return await contract.swap(fromToken, toToken, amount);
  },
  {
    fromToken: "ETH",
    toToken: "USDC",
    amount: "1.5",
  }
);

// Automatically tracks:
// 1. swap_initiated - When transaction starts
// 2. swap_pending - Transaction submitted with txHash
// 3. swap_executed - Transaction confirmed with gasUsed, blockNumber
// 4. swap_failed - If transaction fails (with error details)

The transaction helper captures:

• Transaction hash
• Gas used
• Block number
• Confirmation time
• Error messages (if failed)

This eliminates the need to manually track each transaction state.

Track Custom Events

// Simple event
tracker.track("button_click");

// Event with properties
tracker.track("purchase", {
  productId: "prod_123",
  amount: 99.99,
  currency: "USD",
});

Manual Page View Tracking

// Track page view with custom properties
tracker.trackPageView({
  campaign: "summer_sale",
  source: "email",
});

Configuration Options

interface TrackerConfig {
  // Required: Your tracking endpoint URL
  endpoint: string;

  // Auto-detect wallet connections (MetaMask, Coinbase, etc.)
  // Automatically tracks wallet_connected events and links anonymous activity
  // (default: false)
  autoDetectWallet?: boolean;

  // Enable offline queue with localStorage persistence
  // Events are saved locally and sent when back online
  // (default: true)
  offlineQueue?: boolean;

  // Maximum number of events to store offline
  // (default: 100)
  maxOfflineEvents?: number;

  // Retry configuration for failed requests
  retry?: {
    enabled?: boolean;           // Enable retry logic (default: true)
    maxRetries?: number;         // Max retry attempts (default: 3)
    initialDelay?: number;       // Initial delay in ms (default: 1000)
    backoffMultiplier?: number;  // Exponential backoff multiplier (default: 2)
  };

  // Auto-track page views (default: true)
  autoTrackPageViews?: boolean;

  // Auto-track link clicks (default: true)
  autoTrackClicks?: boolean;

  // Batch size for sending events (0 = send immediately, default: 10)
  batchSize?: number;

  // Max time in ms to wait before sending batch (default: 5000)
  batchTimeout?: number;

  // Include referrer information (default: true)
  includeReferrer?: boolean;

  // Include user agent (default: true)
  includeUserAgent?: boolean;

  // Custom headers for tracking requests
  customHeaders?: Record<string, string>;

  // Enable debug logging (default: false)
  debug?: boolean;
}

Event Structure

All events sent to your endpoint follow this structure:

{
  events: [
    {
      type: "pageview" | "click" | "custom_event_name",
      timestamp: "2024-01-15T10:30:00.000Z",
      url: "https://example.com/page",
      title: "Page Title",
      referrer: "https://google.com",
      userAgent: "Mozilla/5.0...",
      screen: { width: 1920, height: 1080 },
      viewport: { width: 1200, height: 800 },
      sessionId: "1234567890-abcdef",
      user: {
        userId: "12345",
        username: "john_doe",
        wallet: "0x1234...",
        properties: {
          /* custom user properties */
        },
      },
      properties: {
        /* event-specific properties */
      },
    },
  ];
}

Click Events

Click events include additional properties:

{
  type: 'click',
  properties: {
    tagName: 'button',
    id: 'submit-btn',
    className: 'btn btn-primary',
    href: 'https://example.com/link', // for anchor tags
    text: 'Click Me',
    x: 450,  // click coordinates
    y: 200
  }
}

Advanced Usage

Manual Event Flushing

// Flush all queued events immediately
await tracker.flush();

Disable Click Tracking

tracker.disableClickTracking();

Cleanup

// Clean up resources and flush remaining events
tracker.destroy();

Server-Side Endpoint

Your tracking endpoint should accept POST requests with JSON payloads. Here's a simple example using Express:

app.post("/track", express.json(), (req, res) => {
  const { events } = req.body;

  // Store events in your database
  events.forEach((event) => {
    // Add IP address from request
    event.ip = req.ip;

    // Save to database
    db.events.insert(event);
  });

  res.json({ success: true });
});

Building from Source

# Install dependencies
npm install

# Build all formats
npm run build

# Build and watch for changes
npm run dev

Browser Support

• Modern browsers (Chrome, Firefox, Safari, Edge)
• ES2020+ features required
• LocalStorage required for session management

Privacy Considerations

• IP addresses are captured server-side (from request headers)
• User agent strings are optional (configurable)
• No cookies are used
• Session data stored in localStorage only
• All tracking is explicit and configurable

License

MIT

Roadmap

Completed ✅

• ✅ Auto-detect wallet connections (MetaMask, Coinbase, etc.)
• ✅ Offline queue persistence with localStorage
• ✅ Retry logic with exponential backoff
• ✅ Transaction lifecycle tracking helper

Planned

• React integration with hooks
• Next.js plugin
• Vue integration
• Server-side tracking
• Custom storage adapters
• Event validation and schemas
• Performance monitoring
• Multi-wallet management
• GDPR compliance helpers