🎯 Ads Click Tracker

@analytics-debugger/ads-click-tracker

A lightweight, client-side library for tracking and managing ad click IDs across user sessions.

Features

• 💡 Comprehensive Attribution Tracking

  • Automatically capture click IDs from various sources
  • Track landing pages and referrer URLs with precision
  • Store and manage marketing touchpoints effortlessly

• ⏰ Flexible Expiration Management

  • Set custom expiration times for different click sources
  • Automatic cleanup of stale click data
  • Configurable click limits per source

• 🔍 Intelligent URL Parsing

  • Detect parameters in both URL and hash fragments
  • Support for multiple click ID formats (Google, Facebook, custom UTM)

• 💾 Efficient Storage Handling

  • Lightweight localStorage persistence
  • Automatic data management and cleanup
  • Minimal performance overhead

• 🪝 Event callbacks

  • For onLoad, New Click Id found, Updated ClickID

• 🚀 Developer-Friendly

  • Zero dependencies
  • Full TypeScript support
  • < 912 bytes gzipped
  • Simple, intuitive API

Installation

npm install @analytics-debugger/ads-click-tracker
# or
yarn add @analytics-debugger/ads-click-tracker

Quick Start

import AdsClickTracker from '@analytics-debugger/ads-click-tracker'

// Initialize the tracker
const tracker = AdsClickTracker({
  debug: true,
  clickIdConfigs: [
    { name: 'gclid', ttl: 30 * 24 * 60 * 60 * 1000, maxClicks: 100 }, // Google Ads (30 days)
    { name: 'fbclid', ttl: 7 * 24 * 60 * 60 * 1000, maxClicks: 50 }, // Facebook (7 days)
    { name: 'ttclid', ttl: 14 * 24 * 60 * 60 * 1000, maxClicks: 50 }, // TikTok (14 days)
    { name: 'msclkid', ttl: 30 * 24 * 60 * 60 * 1000, maxClicks: 100 } // Microsoft (30 days)
  ],
  callbacks: {
    onLoaded: (clicks) => {
      console.log('Tracker initialized with clicks:', clicks)
    },
    onNewClickId: (click) => {
      console.log('New click ID detected:', click)
    },
    onUpdatedClickId: (click) => {
      console.log('Click ID updated:', click)
    }
  }
})

// Get all tracked clicks
const allClicks = tracker.get()

// Get only the latest click for each source
const latestClicks = tracker.get(true)

// Manually track a click
tracker.track('gclid', 'EAIaIQobChMIh76p9Y3', 2592000000) // value, expiration in ms

// Clear clicks for a specific source
tracker.clear('fbclid')

// Clear all clicks
tracker.clear()

API Reference

Initialization

class AdsClickTracker {
  constructor(options: TrackerOptions)
  // ... other methods
}

TrackerOptions

Option	Type	Default	Description
storageKey	string	'_act_'	Key used for localStorage
clickIdConfigs	ClickConfig[]	required	Array of click ID configurations
debug	boolean	false	Enable debug logging
checkHash	boolean	true	Check hash fragment for click IDs
decodeValues	boolean	true	URL decode click ID values
callbacks	object	{}	Callback functions

ClickConfig

Property	Type	Default	Description
name	string	required	Parameter name to track (e.g., 'gclid')
ttl	number	2592000000 (30 days)	Time in milliseconds before click expires
maxClicks	number	100	Maximum number of clicks to store per source

Methods

get(latest?: boolean): Record<string, ClickData[]>

Get all tracked clicks. If latest is true, returns only the most recent click for each source.

track(source: string, value: string, ttl?: number): void

Manually track a click ID.

clear(source?: string): void

Clear clicks for a specific source or all sources if no source is provided.

ClickData Structure

interface ClickData {
  value: string // Click ID value
  timestamp: number // When the click was recorded
  expiresAt: number // When the click data expires
  landing: string // Landing page URL
  referrer: string // Referrer URL
}

Use Cases

Attribution Tracking

Track which ad campaigns are driving conversions by capturing click IDs when users arrive on your site.

// On your conversion/thank you page
import AdsClickTracker from '@analytics-debugger/ads-click-tracker'

const tracker = AdsClickTracker({
  clickIdConfigs: [
    { name: 'gclid' },
    { name: 'fbclid' }
  ]
})

// Get the latest clicks to include in your conversion tracking
const latestClicks = tracker.get(true)

// Send this data to your analytics or CRM system
sendToAnalytics({
  conversion: true,
  value: 100,
  adClicks: latestClicks
})

Integration with Forms

Automatically include ad click data in your form submissions for attribution.

document.querySelector('#leadForm').addEventListener('submit', (event) => {
  const tracker = initTracker({
    clickIdConfigs: [
      { name: 'gclid' },
      { name: 'fbclid' },
      { name: 'ttclid' },
      { name: 'msclkid' }
    ]
  })

  const latestClicks = tracker.get(true)

  // Add hidden fields to your form with click data
  Object.entries(latestClicks).forEach(([source, clicks]) => {
    if (clicks.length > 0) {
      const hiddenField = document.createElement('input')
      hiddenField.type = 'hidden'
      hiddenField.name = source
      hiddenField.value = clicks[0].value
      event.target.appendChild(hiddenField)
    }
  })
})

Browser Support

AdsClickTracker works in all modern browsers that support localStorage and ES6 features. For older browsers, consider using a transpiler like Babel.

License

MIT

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check issues page.

🌟 Show Your Support

Give a ⭐️ if this project helped you!