New client-side library for tracking ad click IDs launched

The open-source developer community received a new tool for digital marketing and analytics professionals yesterday with the release of a JavaScript library focused on tracking advertisement click identifiers. According to the GitHub repository history, developer David Vallejo released version 0.0.1-beta.2 of the "@analytics-debugger/ads-click-tracker" package, making it available on the npm registry approximately 17 hours ago as of today's date.

This client-side library, written primarily in TypeScript, aims to solve a common challenge that marketers face: capturing, storing, and managing advertisement click identifiers from multiple platforms in a standardized way. The tool operates entirely on the client side, requiring zero dependencies while maintaining a small file size of less than 912 bytes when compressed.

According to the documentation, the library functions by automatically detecting and storing advertisement click identifiers from URLs, including parameters found in both standard URL query strings and hash fragments. This approach addresses a technical gap where marketers previously needed to implement custom solutions to track clicks across different advertising platforms.

The software specifically focuses on capturing click identifiers from major advertising platforms, including Google Ads (gclid), Facebook (fbclid), TikTok (ttclid), and Microsoft Advertising (msclkid). However, the configurable nature of the library allows for tracking custom parameters as well.

A significant technical feature is the library's ability to handle storage constraints through configurable expiration rules. Developers can set different time-to-live (TTL) values for each click source - for example, 30 days for Google Ads clicks and 7 days for Facebook clicks - mirroring each platform's attribution windows. The library then automatically manages the cleanup of expired data.

David Vallejo, who identifies himself as "Analytics OG | Web & App Data Tracking Expert | CEO & Analytics Expert" on LinkedIn, announced the release, stating: "I'm releasing my AdsClick Tracker from my personal repositories! This tool is designed to help you efficiently track and manage clickIds from various vendors."

The implementation follows modern JavaScript practices with a straightforward API. Developers initialize the tracker with configuration settings, defining which parameters to track and how long to retain the data. The library then automatically detects and stores these parameters when present in the URL.

The API provides methods to retrieve all tracked clicks or only the most recent ones, manually track clicks, and clear stored data either for specific sources or entirely. The library stores data in the browser's localStorage, providing persistence across page views without requiring server-side storage.

A detailed examination of the code reveals careful attention to browser compatibility, with the library working in all modern browsers that support localStorage and ES6 features. For developers targeting older browsers, the documentation suggests using a transpiler like Babel.

Storage structure

The data structure used by the library stores each click with comprehensive metadata:

• The click identifier value
• A timestamp marking when the click was recorded
• An expiration timestamp
• The landing page URL
• The referrer URL

This structured approach enables detailed attribution analysis, allowing marketers to understand which advertisements drive conversions and how users navigate through the site after clicking an advertisement.

Professional reception

Initial professional reception appears positive, with the GitHub repository showing early adoption with 4 stars and multiple developers expressing interest. On LinkedIn, Rick Dronkers, who describes himself as providing "High-Impact Data Solutions for Ambitious Marketing Leaders," commented: "Thanks! I've been building something similar let me see if I can merge it with your ideas. One addition I have is that it adds a outgoing hit to a sGTM endpoint to then be stored in firestore."

In response, Vallejo highlighted the library's extensibility: "you can do that from the library itself either querying it on demand, or using the callbacks on the tracker init." This exchange demonstrates the tool's design flexibility for integration with other systems.

Technical use cases

The documentation outlines two primary use cases for the library. First, attribution tracking: capturing click identifiers when users arrive on a site and including this data when recording conversions. Second, form integration: automatically adding hidden fields with click data to forms, allowing this information to be submitted alongside user inputs.

These capabilities address common technical challenges in digital marketing, particularly for businesses tracking multiple advertising campaigns across different platforms. The library simplifies a process that would otherwise require custom implementation for each advertising platform.

According to the npm registry, the package has been downloaded 105 times in the past month, suggesting early adoption among technical marketers and developers despite its beta status.

Licensing and contribution

The library is released under the MIT license, which permits free use, modification, and distribution, both commercially and privately. This licensing choice aligns with open-source best practices, allowing for wide adoption and community contributions.

The GitHub repository explicitly welcomes contributions, issues, and feature requests, suggesting the developer's intent to maintain and grow the project with community input.

Timeline of events

• March 28, 2025: Initial GitHub repository created
• March 29, 2025: Beta version 0.0.1-beta.2 released on npm
• March 29, 2025: David Vallejo announces release on LinkedIn
• March 29, 2025: First community responses and suggestions for integration
• March 30, 2025: Package reaches 105 downloads on npm