{"_id":"@adkit.so/google-tracking","_rev":"4-9470cf6376b515b9763036f93d874d4c","name":"@adkit.so/google-tracking","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@adkit.so/google-tracking","version":"1.0.0","keywords":["google","gtag","google-ads","tracking","conversion","analytics","typescript"],"author":"","license":"MIT","_id":"@adkit.so/google-tracking@1.0.0","maintainers":[{"name":"jeannen","email":"nicolas@jeannen.com"}],"dist":{"shasum":"faa66122df80989ba92c5df9a9a313dbb822f085","tarball":"https://registry.npmjs.org/@adkit.so/google-tracking/-/google-tracking-1.0.0.tgz","fileCount":5,"integrity":"sha512-dzuFJAjzK3gPRKP+9Mq4jhLxihtMErxxYCPpDzHwy+5t81X863TUOgTs722vlabrQ8alniDHs6tKdLBpkOp3LQ==","signatures":[{"sig":"MEQCIBaJEb8Os5rzi/G3EJjcLqa9121/dl63WO5MIxo0dCFNAiA3qcd6xSRYUYsT7X+Ic0Abcg+TG23nYW3la5pzFbyrCQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":12460},"main":"./dist/index.mjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs"}},"scripts":{"test":"vitest run","build":"unbuild","prepack":"npm run build","release":"npm version patch && npm run build && npm publish --access public","test:watch":"vitest"},"_npmUser":{"name":"jeannen","email":"nicolas@jeannen.com"},"_npmVersion":"11.4.2","description":"Platform-agnostic Google Ads tracking wrapper with TypeScript support","directories":{},"_nodeVersion":"23.7.0","_hasShrinkwrap":false,"devDependencies":{"jsdom":"^24.0.0","vitest":"^1.2.0","unbuild":"^2.0.0","typescript":"^5.3.3"},"_npmOperationalInternal":{"tmp":"tmp/google-tracking_1.0.0_1770108775596_0.9505812553564061","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Renamed to @adkit/google-ads-tracking. Install that instead; the API is unchanged."},"1.0.1":{"name":"@adkit.so/google-tracking","version":"1.0.1","keywords":["google","gtag","google-ads","tracking","conversion","analytics","typescript"],"author":"","license":"MIT","_id":"@adkit.so/google-tracking@1.0.1","maintainers":[{"name":"jeannen","email":"nicolas@jeannen.com"}],"dist":{"shasum":"9c5a4966dd3b896f9d597dcf30c76738f3d79723","tarball":"https://registry.npmjs.org/@adkit.so/google-tracking/-/google-tracking-1.0.1.tgz","fileCount":5,"integrity":"sha512-Vz8q9SUSuiHbIOylFlCqaiWDXbg9xS1VuVJ/DIGQLsntPOSicBaaqPHT9sRnZqsEDiCQDpch3U+qb/OPm2QGgw==","signatures":[{"sig":"MEUCIEoWLbeyMuFjVegFaRPq8We+pIKZ2sIMN0yXtwKYsosdAiEA4WPLFgjeK3mR7SSHOiaUp5QarVeZl3iZ9uI/uVUn+ys=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":18407},"main":"./dist/index.mjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs"}},"scripts":{"test":"vitest run","build":"unbuild","prepack":"npm run build","release":"npm version patch && npm run build && npm publish --access public","test:watch":"vitest"},"_npmUser":{"name":"jeannen","email":"nicolas@jeannen.com"},"_npmVersion":"11.4.2","description":"Platform-agnostic Google Ads tracking wrapper with TypeScript support","directories":{},"_nodeVersion":"23.7.0","_hasShrinkwrap":false,"devDependencies":{"jsdom":"^24.0.0","vitest":"^1.2.0","unbuild":"^2.0.0","typescript":"^5.3.3"},"_npmOperationalInternal":{"tmp":"tmp/google-tracking_1.0.1_1770108908535_0.5375059324679128","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Renamed to @adkit/google-ads-tracking. Install that instead; the API is unchanged."},"1.0.2":{"name":"@adkit.so/google-tracking","version":"1.0.2","keywords":["google","gtag","google-ads","tracking","conversion","analytics","typescript"],"author":"","license":"MIT","_id":"@adkit.so/google-tracking@1.0.2","maintainers":[{"name":"jeannen","email":"nicolas@jeannen.com"}],"dist":{"shasum":"e905dcb98594dd9248d0bb5eadbfd8080663b860","tarball":"https://registry.npmjs.org/@adkit.so/google-tracking/-/google-tracking-1.0.2.tgz","fileCount":5,"integrity":"sha512-iQy6saPRZNs0B9I07ldtPoa9ZQH786pVIQGfJ4pbSyzpFagaXMmOvHPQWzHbGj7ne4N0wofMTDQYN4w1oYPceQ==","signatures":[{"sig":"MEYCIQCe0l56zJZJpikDJrv+Zr2z0OVDDyE6+o18jRilbgiNfgIhANhjndNzV4u5GS9ED7Xr+X+4qQQzvmPNwnrxGj6Lyl+l","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":18840},"main":"./dist/index.mjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs"}},"scripts":{"test":"vitest run","build":"unbuild","prepack":"npm run build","release":"npm version patch && npm run build && npm publish --access public","test:watch":"vitest"},"_npmUser":{"name":"jeannen","email":"nicolas@jeannen.com"},"_npmVersion":"11.4.2","description":"Platform-agnostic Google Ads tracking wrapper with TypeScript support","directories":{},"_nodeVersion":"23.7.0","_hasShrinkwrap":false,"devDependencies":{"jsdom":"^24.0.0","vitest":"^1.2.0","unbuild":"^2.0.0","typescript":"^5.3.3"},"_npmOperationalInternal":{"tmp":"tmp/google-tracking_1.0.2_1770109797395_0.9434278162844201","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Renamed to @adkit/google-ads-tracking. Install that instead; the API is unchanged."}},"time":{"created":"2026-02-03T08:52:55.478Z","modified":"2026-07-30T04:03:46.575Z","1.0.0":"2026-02-03T08:52:55.725Z","1.0.1":"2026-02-03T08:55:08.674Z","1.0.2":"2026-02-03T09:09:57.539Z"},"license":"MIT","keywords":["google","gtag","google-ads","tracking","conversion","analytics","typescript"],"description":"Platform-agnostic Google Ads tracking wrapper with TypeScript support","maintainers":[{"name":"jeannen","email":"nicolas@jeannen.com"}],"readme":"# Google Ads Tracking (JS/TS)\n\n[![npm version](https://img.shields.io/npm/v/@adkit.so/google-tracking.svg)](https://www.npmjs.com/package/@adkit.so/google-tracking)\n[![npm downloads](https://img.shields.io/npm/dm/@adkit.so/google-tracking.svg)](https://www.npmjs.com/package/@adkit.so/google-tracking)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n> A lightweight, type-safe Google Ads (gtag.js) tracking wrapper for JavaScript & TypeScript applications.\n\nPlatform-agnostic wrapper for Google Ads conversion tracking with TypeScript support, debug logging, and automatic script loading.\n\n## 📚 Table of Contents\n\n- [Features](#-features)\n- [Quick Start](#-quick-start)\n- [Installation](#-installation)\n- [Usage](#-usage)\n- [Configuration](#%EF%B8%8F-configuration)\n- [Tracking Conversions](#-tracking-conversions)\n- [Advanced Usage](#-advanced-usage)\n- [TypeScript Support](#-typescript-support)\n- [Troubleshooting](#-troubleshooting)\n- [Official Documentation](#-official-documentation)\n- [License](#-license)\n\n## ✨ Features\n\n- ✅ **TypeScript Support** - Full TypeScript support with type definitions\n- 🎯 **Conversion Tracking** - Easy Google Ads conversion tracking with flexible parameters\n- 🔌 **Auto Script Loading** - Automatically loads gtag.js script\n- 🐛 **Debug Mode** - Beautiful styled console logs for development\n- 🏠 **Localhost Support** - Easy configuration to enable/disable tracking on localhost\n- 📦 **Lightweight** - Minimal footprint (~2KB minified)\n\n## ⚡ Quick Start\n\n```bash\nnpm install @adkit.so/google-tracking\n```\n\n```typescript\nimport GOOGLE from '@adkit.so/google-tracking';\n\n// 1. Initialize\nGOOGLE.init({ tagId: 'AW-XXXXXXXXXX' });\n\n// 2. Track conversions\nGOOGLE.trackConversion('AW-XXXXXXXXXX/YYYYYYY', { value: 29.99, currency: 'USD' });\n```\n\nThat's it! 🎉\n\n## 📦 Installation\n\n```bash\nnpm install @adkit.so/google-tracking\n```\n\n## 💡 Usage\n\n### Basic Initialization\n\nInitialize the tracker as early as possible in your application entry point (e.g., `main.ts`, `App.jsx`, `index.js`).\n\n```typescript\nimport GOOGLE from '@adkit.so/google-tracking';\n\nGOOGLE.init({\n    tagId: 'AW-XXXXXXXXXX',\n    debug: true, // Enable console logs\n    enableLocalhost: true, // Enable on localhost for testing\n});\n```\n\n### Tracking Conversions\n\n```typescript\n// Basic conversion (no value)\nGOOGLE.trackConversion('AW-XXXXXXXXXX/CONVERSION_LABEL');\n\n// Conversion with value\nGOOGLE.trackConversion('AW-XXXXXXXXXX/CONVERSION_LABEL', {\n    value: 99.99,\n    currency: 'USD',\n});\n\n// Conversion with transaction ID (for deduplication)\nGOOGLE.trackConversion('AW-XXXXXXXXXX/CONVERSION_LABEL', {\n    value: 99.99,\n    currency: 'USD',\n    transaction_id: 'ORDER_12345',\n});\n```\n\n### Multiple Instances\n\nIf you need separate instances for different parts of your application:\n\n```typescript\nimport { createGoogleTracking } from '@adkit.so/google-tracking';\n\nconst tracker1 = createGoogleTracking();\ntracker1.init({ tagId: 'AW-FIRST_TAG' });\n\nconst tracker2 = createGoogleTracking();\ntracker2.init({ tagId: 'AW-SECOND_TAG' });\n```\n\n## ⚙️ Configuration\n\n### Configuration Options\n\n| Option            | Type                 | Default | Description                                                    |\n| ----------------- | -------------------- | ------- | -------------------------------------------------------------- |\n| `tagId`           | `string \\| string[]` | `''`    | **Required.** Single Tag ID or array of Tag IDs (e.g., `AW-XXXXX`) |\n| `debug`           | `boolean`            | `false` | Enable styled console logs with background colors              |\n| `enableLocalhost` | `boolean`            | `false` | Enable tracking on localhost (useful for testing)              |\n\n### Multiple Tags Example\n\n```typescript\nGOOGLE.init({\n    tagId: ['AW-FIRST_TAG', 'AW-SECOND_TAG'],\n    debug: true,\n});\n```\n\n## 📊 Tracking Conversions\n\n### Conversion Parameters\n\n| Parameter        | Type     | Description                     | Example          |\n| ---------------- | -------- | ------------------------------- | ---------------- |\n| `value`          | `number` | Monetary value of the conversion | `99.99`          |\n| `currency`       | `string` | ISO 4217 currency code          | `'USD'`, `'EUR'` |\n| `transaction_id` | `string` | Unique ID for deduplication     | `'ORDER_12345'`  |\n\n### Common Conversion Examples\n\n```typescript\n// E-commerce purchase\nGOOGLE.trackConversion('AW-XXXXX/purchase_label', {\n    value: 149.99,\n    currency: 'USD',\n    transaction_id: 'order_abc123',\n});\n\n// Lead form submission\nGOOGLE.trackConversion('AW-XXXXX/lead_label');\n\n// Sign-up conversion\nGOOGLE.trackConversion('AW-XXXXX/signup_label', {\n    value: 10.0,\n    currency: 'USD',\n});\n\n// Subscription conversion\nGOOGLE.trackConversion('AW-XXXXX/subscribe_label', {\n    value: 29.0,\n    currency: 'USD',\n    transaction_id: 'sub_xyz789',\n});\n```\n\n## 🚀 Advanced Usage\n\n### Check if Loaded\n\nUseful if you need to conditionally run logic based on whether gtag has loaded.\n\n```typescript\nif (GOOGLE.isLoaded()) {\n    GOOGLE.trackConversion('AW-XXXXX/label');\n} else {\n    console.log('Google Ads not loaded yet');\n}\n```\n\n### Get Current Configuration\n\n```typescript\nconst config = GOOGLE.getConfig();\nconsole.log(config?.tagId); // 'AW-XXXXX'\n```\n\n### Debug Mode\n\nWhen `debug: true` is passed to `init()`, you'll see beautiful styled console logs:\n\n- 🔵 **[Google Tracking]** Info messages (blue background)\n- ✅ **[Google Tracking]** Success messages (green background)\n- ⚠️ **[Google Tracking]** Warning messages (orange background)\n\n```typescript\nGOOGLE.init({\n    tagId: 'AW-XXXXX',\n    debug: true,\n});\n```\n\n## 📝 TypeScript Support\n\nThis package is written in TypeScript and bundles type definitions.\n\n```typescript\nimport type { GoogleTrackingConfig, ConversionParams } from '@adkit.so/google-tracking';\n\nconst config: GoogleTrackingConfig = {\n    tagId: 'AW-XXXXX',\n    debug: true,\n};\n\nconst params: ConversionParams = {\n    value: 100,\n    currency: 'USD',\n    transaction_id: 'order_123',\n};\n```\n\n## ❓ Troubleshooting\n\n### Conversions not tracking?\n\n1. **Check your Tag ID** - Make sure it's correct (format: `AW-XXXXXXXXXX`)\n2. **Check Conversion ID** - Full format: `AW-XXXXXXXXXX/CONVERSION_LABEL`\n3. **Enable debug mode** - Set `debug: true` in `init()` to see detailed logs\n4. **Check browser console** - Look for errors or warnings\n5. **Check Ad Blockers** - Ad blockers may block Google tracking scripts\n6. **Enable on localhost** - Set `enableLocalhost: true` if testing locally\n\n### Conversions not showing in Google Ads?\n\n- **Wait up to 24 hours** - Conversions can take time to appear\n- **Check Google Tag Assistant** - Use the Chrome extension to verify tags\n- **Verify conversion action** - Ensure the conversion is set up in Google Ads\n\n## 📚 Official Documentation\n\nLearn more about Google Ads conversion tracking:\n\n- **[Google Ads Conversion Tracking](https://support.google.com/google-ads/answer/1722054)** - Getting started guide\n- **[gtag.js Reference](https://developers.google.com/tag-platform/gtagjs/reference)** - Complete API reference\n- **[Event Snippets](https://support.google.com/google-ads/answer/7548399)** - Conversion tracking setup\n- **[Google Tag Assistant](https://tagassistant.google.com/)** - Debug your tags\n\n## 🔗 Related Packages\n\nCheck out our other tracking packages:\n\n- [**Meta Pixel**](https://www.npmjs.com/package/@adkit.so/meta-pixel) - `@adkit.so/meta-pixel`\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## 📄 License\n\nMIT\n\n---\n\n**Made with ❤️ by [AdKit](https://adkit.so)**\n\nIf this package helped you, please consider giving it a ⭐️ on GitHub!\n","readmeFilename":"README.md"}