{"_id":"@analytics-debugger/ads-click-tracker","_rev":"3-8d4cde5c2361d1b43ba15b9589550ce8","name":"@analytics-debugger/ads-click-tracker","dist-tags":{"latest":"0.0.1-beta.3"},"versions":{"0.0.1-beta.1":{"name":"@analytics-debugger/ads-click-tracker","version":"0.0.1-beta.1","keywords":[],"author":{"name":"David Vallejo","email":"thyngster@gmail.com"},"license":"MIT","_id":"@analytics-debugger/ads-click-tracker@0.0.1-beta.1","maintainers":[{"name":"thyngster","email":"thyngster@gmail.com"}],"homepage":"https://github.com/analytics-debugger/ads-click-tracker#readme","bugs":{"url":"https://github.com/analytics-debugger/ads-click-tracker/issues"},"dist":{"shasum":"1dd006da295df9e636fbdd6cf6c8e5b9c59e8422","tarball":"https://registry.npmjs.org/@analytics-debugger/ads-click-tracker/-/ads-click-tracker-0.0.1-beta.1.tgz","fileCount":10,"integrity":"sha512-hV9AppLfqa0p2hkRnKwt5BozYBdGX1ACN5iMQL6TXUtK3+HLHTJ8PIfWW8TCN2CEi1zx8PxQ7SctXH58WnzY9A==","signatures":[{"sig":"MEUCIDm88plaXcQ3X63uU6FDi7Wa0Smqzh5OK6kEVAvkHgL5AiEA2W52h/ae6+L8QgFe8HMNVUufbcwErtrzY2ATkQbOEuk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27960},"main":"./dist/index.mjs","type":"module","_from":"file:analytics-debugger-ads-click-tracker-0.0.1-beta.1.tgz","types":"./dist/index.d.mts","module":"./dist/index.mjs","exports":{".":"./dist/index.mjs","./package.json":"./package.json"},"funding":"https://github.com/sponsors/thyngster","scripts":{"dev":"unbuild --stub","bump":"bumpp","lint":"eslint","test":"vitest","build":"unbuild","start":"tsx src/index.ts","release":"bumpp && pnpm publish","typecheck":"tsc --noEmit","npmPublish":"pnpm publish --access public"},"_npmUser":{"name":"thyngster","email":"thyngster@gmail.com"},"_resolved":"C:\\Users\\David\\AppData\\Local\\Temp\\609006e3f0e8570d1331a61341026947\\analytics-debugger-ads-click-tracker-0.0.1-beta.1.tgz","_integrity":"sha512-hV9AppLfqa0p2hkRnKwt5BozYBdGX1ACN5iMQL6TXUtK3+HLHTJ8PIfWW8TCN2CEi1zx8PxQ7SctXH58WnzY9A==","repository":{"url":"git+https://github.com/analytics-debugger/ads-click-tracker.git","type":"git"},"_npmVersion":"10.9.2","description":"Library to keep track of clickIds from different advertising platforms","directories":{},"lint-staged":{"*":"eslint --fix"},"sideEffects":false,"_nodeVersion":"22.14.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.3","vite":"^6.2.1","yaml":"^2.7.0","bumpp":"^10.1.0","eslint":"^9.22.0","vitest":"^3.0.8","unbuild":"^3.5.0","tinyexec":"^0.3.2","@antfu/ni":"^24.1.0","typescript":"^5.8.2","@types/node":"^22.13.10","lint-staged":"^15.5.0","@antfu/utils":"^9.1.0","simple-git-hooks":"^2.11.1","@antfu/eslint-config":"^4.10.1","vitest-package-exports":"^0.1.1"},"simple-git-hooks":{"pre-commit":"pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"},"_npmOperationalInternal":{"tmp":"tmp/ads-click-tracker_0.0.1-beta.1_1743220463277_0.1742358205679002","host":"s3://npm-registry-packages-npm-production"}},"0.0.1-beta.2":{"name":"@analytics-debugger/ads-click-tracker","version":"0.0.1-beta.2","keywords":[],"author":{"name":"David Vallejo","email":"thyngster@gmail.com"},"license":"MIT","_id":"@analytics-debugger/ads-click-tracker@0.0.1-beta.2","maintainers":[{"name":"thyngster","email":"thyngster@gmail.com"}],"homepage":"https://github.com/analytics-debugger/ads-click-tracker#readme","bugs":{"url":"https://github.com/analytics-debugger/ads-click-tracker/issues"},"dist":{"shasum":"941a1a714d375091c17433baacebf72945c190ef","tarball":"https://registry.npmjs.org/@analytics-debugger/ads-click-tracker/-/ads-click-tracker-0.0.1-beta.2.tgz","fileCount":10,"integrity":"sha512-NLi56eiltOXdLIlUD3vasHqOaHcfbWeTMNSBTC8xk4jhnwOo/dFuH+QWQ59sEy6xU11QhEEnRZSjObdFrjMxIg==","signatures":[{"sig":"MEYCIQDSAhOg2yE7B3rlO5FauQtTywI7L3FtpgxylO59RmiRKwIhAIeRa9IrFhPBL4rJVYmtnWFCimOC/U2RmEclv7dYtwHV","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":31961},"main":"./dist/index.mjs","type":"module","_from":"file:analytics-debugger-ads-click-tracker-0.0.1-beta.2.tgz","types":"./dist/index.d.mts","module":"./dist/index.mjs","exports":{".":"./dist/index.mjs","./package.json":"./package.json"},"funding":"https://github.com/sponsors/thyngster","scripts":{"dev":"unbuild --stub","bump":"bumpp","lint":"eslint","test":"vitest","build":"unbuild","start":"tsx src/index.ts","release":"bumpp && pnpm publish","typecheck":"tsc --noEmit","npmPublish":"pnpm publish --access public"},"_npmUser":{"name":"thyngster","email":"thyngster@gmail.com"},"_resolved":"C:\\Users\\David\\AppData\\Local\\Temp\\52924a39776bc6bef20d56b6b051261d\\analytics-debugger-ads-click-tracker-0.0.1-beta.2.tgz","_integrity":"sha512-NLi56eiltOXdLIlUD3vasHqOaHcfbWeTMNSBTC8xk4jhnwOo/dFuH+QWQ59sEy6xU11QhEEnRZSjObdFrjMxIg==","repository":{"url":"git+https://github.com/analytics-debugger/ads-click-tracker.git","type":"git"},"_npmVersion":"10.9.2","description":"Library to keep track of clickIds from different advertising platforms","directories":{},"lint-staged":{"*":"eslint --fix"},"sideEffects":false,"_nodeVersion":"22.14.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.3","vite":"^6.2.1","yaml":"^2.7.0","bumpp":"^10.1.0","eslint":"^9.22.0","vitest":"^3.0.8","unbuild":"^3.5.0","tinyexec":"^0.3.2","@antfu/ni":"^24.1.0","typescript":"^5.8.2","@types/node":"^22.13.10","lint-staged":"^15.5.0","@antfu/utils":"^9.1.0","simple-git-hooks":"^2.11.1","@antfu/eslint-config":"^4.10.1","vitest-package-exports":"^0.1.1"},"simple-git-hooks":{"pre-commit":"pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"},"_npmOperationalInternal":{"tmp":"tmp/ads-click-tracker_0.0.1-beta.2_1743291386325_0.26827912737551274","host":"s3://npm-registry-packages-npm-production"}},"0.0.1-beta.3":{"name":"@analytics-debugger/ads-click-tracker","type":"module","version":"0.0.1-beta.3","description":"Library to keep track of clickIds from different advertising platforms","author":{"name":"David Vallejo","email":"thyngster@gmail.com"},"license":"MIT","funding":"https://github.com/sponsors/thyngster","homepage":"https://github.com/analytics-debugger/ads-click-tracker#readme","repository":{"type":"git","url":"git+https://github.com/analytics-debugger/ads-click-tracker.git"},"bugs":{"url":"https://github.com/analytics-debugger/ads-click-tracker/issues"},"keywords":[],"sideEffects":false,"exports":{".":{"import":"./dist/index.mjs","./package.json":"./package.json"}},"main":"./dist/index.mjs","module":"./dist/index.mjs","types":"./dist/index.d.mts","devDependencies":{"@antfu/eslint-config":"^4.10.1","@antfu/ni":"^24.1.0","@antfu/utils":"^9.1.0","@rollup/plugin-terser":"^0.4.4","@types/node":"^22.13.10","bumpp":"^10.1.0","eslint":"^9.22.0","lint-staged":"^15.5.0","simple-git-hooks":"^2.11.1","tinyexec":"^0.3.2","tsx":"^4.19.3","typescript":"^5.8.2","unbuild":"^3.5.0","vite":"^6.2.1","vitest":"^3.0.8","vitest-package-exports":"^0.1.1","yaml":"^2.7.0"},"simple-git-hooks":{"pre-commit":"pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"},"lint-staged":{"*":"eslint --fix"},"scripts":{"build":"unbuild","dev":"unbuild --stub","lint":"eslint","bump":"bumpp","npmPublish":"pnpm publish --access public","release":"bumpp && pnpm publish","start":"tsx src/index.ts","test":"vitest","typecheck":"tsc --noEmit"},"_id":"@analytics-debugger/ads-click-tracker@0.0.1-beta.3","_integrity":"sha512-1uslbPevsjume8XJq5bula64I+FBwt/r1UcK29e1QZqausFx5rLZ8ceknjxsjwb6oi6Pk0HB3pFLnDd07MOwIA==","_resolved":"C:\\Users\\David\\AppData\\Local\\Temp\\7864daf8211c3ed98dae937780f9d07f\\analytics-debugger-ads-click-tracker-0.0.1-beta.3.tgz","_from":"file:analytics-debugger-ads-click-tracker-0.0.1-beta.3.tgz","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-1uslbPevsjume8XJq5bula64I+FBwt/r1UcK29e1QZqausFx5rLZ8ceknjxsjwb6oi6Pk0HB3pFLnDd07MOwIA==","shasum":"1bf96c8d7f300d1c5a64c412f308e0bbba971a06","tarball":"https://registry.npmjs.org/@analytics-debugger/ads-click-tracker/-/ads-click-tracker-0.0.1-beta.3.tgz","fileCount":14,"unpackedSize":41128,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGRjT1ugjqmAtcy1xOClMfV4iMLnVL8wGUMMoJYjKd7NAiEA3G7yEPcl+1KY+8tawNI3r/gDwwQ2W3BDX8WsqkCHtfg="}]},"_npmUser":{"name":"thyngster","email":"thyngster@gmail.com"},"directories":{},"maintainers":[{"name":"thyngster","email":"thyngster@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ads-click-tracker_0.0.1-beta.3_1743454646253_0.23092219207532483"},"_hasShrinkwrap":false}},"time":{"created":"2025-03-29T03:54:23.185Z","modified":"2025-03-31T20:57:26.652Z","0.0.1-beta.1":"2025-03-29T03:54:23.434Z","0.0.1-beta.2":"2025-03-29T23:36:26.545Z","0.0.1-beta.3":"2025-03-31T20:57:26.454Z"},"bugs":{"url":"https://github.com/analytics-debugger/ads-click-tracker/issues"},"author":{"name":"David Vallejo","email":"thyngster@gmail.com"},"license":"MIT","homepage":"https://github.com/analytics-debugger/ads-click-tracker#readme","keywords":[],"repository":{"type":"git","url":"git+https://github.com/analytics-debugger/ads-click-tracker.git"},"description":"Library to keep track of clickIds from different advertising platforms","maintainers":[{"name":"thyngster","email":"thyngster@gmail.com"}],"readme":"# 🎯 Ads Click Tracker\r\n\r\n[![npm version](https://img.shields.io/npm/v/@analytics-debugger/ads-click-tracker)](https://www.npmjs.com/package/@analytics-debugger/ads-click-tracker)\r\n[![bundle size](https://bundlephobia.com/package/@analytics-debugger/ads-click-tracker)](https://bundlephobia.com/package/@analytics-debugger/ads-click-tracker@latest)\r\n[![license](https://img.shields.io/npm/l/@analytics-debugger/ads-click-tracker)](LICENSE)\r\n[![Downloads](https://img.shields.io/npm/dm/@analytics-debugger/ads-click-tracker)](https://www.npmjs.com/package/@analytics-debugger/ads-click-tracker)\r\n\r\n# @analytics-debugger/ads-click-tracker\r\n\r\nA lightweight, client-side library for tracking and managing ad click IDs across user sessions.\r\n\r\n## Features\r\n\r\n- **💡 Comprehensive Attribution Tracking**\r\n  - Automatically capture click IDs from various sources\r\n  - Track landing pages and referrer URLs with precision\r\n  - Store and manage marketing touchpoints effortlessly\r\n\r\n- **⏰ Flexible Expiration Management**\r\n  - Set custom expiration times for different click sources\r\n  - Automatic cleanup of stale click data\r\n  - Configurable click limits per source\r\n\r\n- **🔍 Intelligent URL Parsing**\r\n  - Detect parameters in both URL and hash fragments\r\n  - Support for multiple click ID formats (Google, Facebook, custom UTM)\r\n\r\n- **💾 Efficient Storage Handling**\r\n  - Lightweight localStorage persistence\r\n  - Automatic data management and cleanup\r\n  - Minimal performance overhead\r\n\r\n- **🪝  Event callbacks**\r\n   - For onLoad, New Click Id found, Updated ClickID\r\n\r\n- **🚀 Developer-Friendly**\r\n  - Zero dependencies\r\n  - Full TypeScript support\r\n  - < 912 bytes gzipped\r\n  - Simple, intuitive API\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @analytics-debugger/ads-click-tracker\r\n# or\r\nyarn add @analytics-debugger/ads-click-tracker\r\n```\r\n\r\n## Quick Start\r\n\r\n```javascript\r\nimport AdsClickTracker from '@analytics-debugger/ads-click-tracker'\r\n\r\n// Initialize the tracker\r\nconst tracker = AdsClickTracker({\r\n  debug: true,\r\n  clickIdConfigs: [\r\n    { name: 'gclid', ttl: 30 * 24 * 60 * 60 * 1000, maxClicks: 100 }, // Google Ads (30 days)\r\n    { name: 'fbclid', ttl: 7 * 24 * 60 * 60 * 1000, maxClicks: 50 }, // Facebook (7 days)\r\n    { name: 'ttclid', ttl: 14 * 24 * 60 * 60 * 1000, maxClicks: 50 }, // TikTok (14 days)\r\n    { name: 'msclkid', ttl: 30 * 24 * 60 * 60 * 1000, maxClicks: 100 } // Microsoft (30 days)\r\n  ],\r\n  callbacks: {\r\n    onLoaded: (clicks) => {\r\n      console.log('Tracker initialized with clicks:', clicks)\r\n    },\r\n    onNewClickId: (click) => {\r\n      console.log('New click ID detected:', click)\r\n    },\r\n    onUpdatedClickId: (click) => {\r\n      console.log('Click ID updated:', click)\r\n    }\r\n  }\r\n})\r\n\r\n// Get all tracked clicks\r\nconst allClicks = tracker.get()\r\n\r\n// Get only the latest click for each source\r\nconst latestClicks = tracker.get(true)\r\n\r\n// Manually track a click\r\ntracker.track('gclid', 'EAIaIQobChMIh76p9Y3', 2592000000) // value, expiration in ms\r\n\r\n// Clear clicks for a specific source\r\ntracker.clear('fbclid')\r\n\r\n// Clear all clicks\r\ntracker.clear()\r\n```\r\n\r\n## API Reference\r\n\r\n### Initialization\r\n\r\n```typescript\r\nclass AdsClickTracker {\r\n  constructor(options: TrackerOptions)\r\n  // ... other methods\r\n}\r\n```\r\n\r\n#### TrackerOptions\r\n\r\n| Option | Type | Default | Description |\r\n|--------|------|---------|-------------|\r\n| `storageKey` | string | `'_act_'` | Key used for localStorage |\r\n| `clickIdConfigs` | ClickConfig[] | *required* | Array of click ID configurations |\r\n| `debug` | boolean | `false` | Enable debug logging |\r\n| `checkHash` | boolean | `true` | Check hash fragment for click IDs |\r\n| `decodeValues` | boolean | `true` | URL decode click ID values |\r\n| `callbacks` | object | `{}` | Callback functions |\r\n\r\n#### ClickConfig\r\n\r\n| Property | Type | Default | Description |\r\n|----------|------|---------|-------------|\r\n| `name` | string | *required* | Parameter name to track (e.g., 'gclid') |\r\n| `ttl` | number | `2592000000` (30 days) | Time in milliseconds before click expires |\r\n| `maxClicks` | number | `100` | Maximum number of clicks to store per source |\r\n\r\n### Methods\r\n\r\n#### get(latest?: boolean): Record<string, ClickData[]>\r\n\r\nGet all tracked clicks. If `latest` is `true`, returns only the most recent click for each source.\r\n\r\n#### track(source: string, value: string, ttl?: number): void\r\n\r\nManually track a click ID.\r\n\r\n#### clear(source?: string): void\r\n\r\nClear clicks for a specific source or all sources if no source is provided.\r\n\r\n### ClickData Structure\r\n\r\n```typescript\r\ninterface ClickData {\r\n  value: string // Click ID value\r\n  timestamp: number // When the click was recorded\r\n  expiresAt: number // When the click data expires\r\n  landing: string // Landing page URL\r\n  referrer: string // Referrer URL\r\n}\r\n```\r\n\r\n## Use Cases\r\n\r\n### Attribution Tracking\r\n\r\nTrack which ad campaigns are driving conversions by capturing click IDs when users arrive on your site.\r\n\r\n```javascript\r\n// On your conversion/thank you page\r\nimport AdsClickTracker from '@analytics-debugger/ads-click-tracker'\r\n\r\nconst tracker = AdsClickTracker({\r\n  clickIdConfigs: [\r\n    { name: 'gclid' },\r\n    { name: 'fbclid' }\r\n  ]\r\n})\r\n\r\n// Get the latest clicks to include in your conversion tracking\r\nconst latestClicks = tracker.get(true)\r\n\r\n// Send this data to your analytics or CRM system\r\nsendToAnalytics({\r\n  conversion: true,\r\n  value: 100,\r\n  adClicks: latestClicks\r\n})\r\n```\r\n\r\n### Integration with Forms\r\n\r\nAutomatically include ad click data in your form submissions for attribution.\r\n\r\n```javascript\r\ndocument.querySelector('#leadForm').addEventListener('submit', (event) => {\r\n  const tracker = initTracker({\r\n    clickIdConfigs: [\r\n      { name: 'gclid' },\r\n      { name: 'fbclid' },\r\n      { name: 'ttclid' },\r\n      { name: 'msclkid' }\r\n    ]\r\n  })\r\n\r\n  const latestClicks = tracker.get(true)\r\n\r\n  // Add hidden fields to your form with click data\r\n  Object.entries(latestClicks).forEach(([source, clicks]) => {\r\n    if (clicks.length > 0) {\r\n      const hiddenField = document.createElement('input')\r\n      hiddenField.type = 'hidden'\r\n      hiddenField.name = source\r\n      hiddenField.value = clicks[0].value\r\n      event.target.appendChild(hiddenField)\r\n    }\r\n  })\r\n})\r\n```\r\n\r\n## Browser Support\r\n\r\nAdsClickTracker works in all modern browsers that support localStorage and ES6 features. For older browsers, consider using a transpiler like Babel.\r\n\r\n## License\r\n\r\nMIT\r\n\r\n## 🤝 Contributing\r\n\r\nContributions, issues, and feature requests are welcome!\r\nFeel free to check [issues page](https://github.com/yourusername/ads-click-tracker/issues).\r\n\r\n## 🌟 Show Your Support\r\n\r\nGive a ⭐️ if this project helped you!\r\n","readmeFilename":"README.md"}