Google Ads Tracking (JS/TS)

A lightweight, type-safe Google Ads (gtag.js) tracking wrapper for JavaScript & TypeScript applications.

Platform-agnostic wrapper for Google Ads conversion tracking with TypeScript support, debug logging, and automatic script loading.

📚 Table of Contents

• Features
• Quick Start
• Installation
• Usage
• Configuration
• Tracking Conversions
• Advanced Usage
• TypeScript Support
• Troubleshooting
• Official Documentation
• License

✨ Features

• ✅ TypeScript Support - Full TypeScript support with type definitions
• 🎯 Conversion Tracking - Easy Google Ads conversion tracking with flexible parameters
• 🔌 Auto Script Loading - Automatically loads gtag.js script
• 🐛 Debug Mode - Beautiful styled console logs for development
• 🏠 Localhost Support - Easy configuration to enable/disable tracking on localhost
• 📦 Lightweight - Minimal footprint (~2KB minified)

⚡ Quick Start

npm install @adkit.so/google-tracking

import GOOGLE from '@adkit.so/google-tracking';

// 1. Initialize
GOOGLE.init({ tagId: 'AW-XXXXXXXXXX' });

// 2. Track conversions
GOOGLE.trackConversion('AW-XXXXXXXXXX/YYYYYYY', { value: 29.99, currency: 'USD' });

That's it! 🎉

📦 Installation

npm install @adkit.so/google-tracking

💡 Usage

Basic Initialization

Initialize the tracker as early as possible in your application entry point (e.g., main.ts, App.jsx, index.js).

import GOOGLE from '@adkit.so/google-tracking';

GOOGLE.init({
    tagId: 'AW-XXXXXXXXXX',
    debug: true, // Enable console logs
    enableLocalhost: true, // Enable on localhost for testing
});

Tracking Conversions

// Basic conversion (no value)
GOOGLE.trackConversion('AW-XXXXXXXXXX/CONVERSION_LABEL');

// Conversion with value
GOOGLE.trackConversion('AW-XXXXXXXXXX/CONVERSION_LABEL', {
    value: 99.99,
    currency: 'USD',
});

// Conversion with transaction ID (for deduplication)
GOOGLE.trackConversion('AW-XXXXXXXXXX/CONVERSION_LABEL', {
    value: 99.99,
    currency: 'USD',
    transaction_id: 'ORDER_12345',
});

Multiple Instances

If you need separate instances for different parts of your application:

import { createGoogleTracking } from '@adkit.so/google-tracking';

const tracker1 = createGoogleTracking();
tracker1.init({ tagId: 'AW-FIRST_TAG' });

const tracker2 = createGoogleTracking();
tracker2.init({ tagId: 'AW-SECOND_TAG' });

⚙️ Configuration

Configuration Options

| Option | Type | Default | Description | | ----------------- | -------------------- | ------- | -------------------------------------------------------------- | | tagId | string \| string[] | '' | Required. Single Tag ID or array of Tag IDs (e.g., AW-XXXXX) | | debug | boolean | false | Enable styled console logs with background colors | | enableLocalhost | boolean | false | Enable tracking on localhost (useful for testing) |

Multiple Tags Example

GOOGLE.init({
    tagId: ['AW-FIRST_TAG', 'AW-SECOND_TAG'],
    debug: true,
});

📊 Tracking Conversions

Conversion Parameters

| Parameter | Type | Description | Example | | ---------------- | -------- | ------------------------------- | ---------------- | | value | number | Monetary value of the conversion | 99.99 | | currency | string | ISO 4217 currency code | 'USD', 'EUR' | | transaction_id | string | Unique ID for deduplication | 'ORDER_12345' |

Common Conversion Examples

// E-commerce purchase
GOOGLE.trackConversion('AW-XXXXX/purchase_label', {
    value: 149.99,
    currency: 'USD',
    transaction_id: 'order_abc123',
});

// Lead form submission
GOOGLE.trackConversion('AW-XXXXX/lead_label');

// Sign-up conversion
GOOGLE.trackConversion('AW-XXXXX/signup_label', {
    value: 10.0,
    currency: 'USD',
});

// Subscription conversion
GOOGLE.trackConversion('AW-XXXXX/subscribe_label', {
    value: 29.0,
    currency: 'USD',
    transaction_id: 'sub_xyz789',
});

🚀 Advanced Usage

Check if Loaded

Useful if you need to conditionally run logic based on whether gtag has loaded.

if (GOOGLE.isLoaded()) {
    GOOGLE.trackConversion('AW-XXXXX/label');
} else {
    console.log('Google Ads not loaded yet');
}

Get Current Configuration

const config = GOOGLE.getConfig();
console.log(config?.tagId); // 'AW-XXXXX'

Debug Mode

When debug: true is passed to init(), you'll see beautiful styled console logs:

• 🔵 [Google Tracking] Info messages (blue background)
• ✅ [Google Tracking] Success messages (green background)
• ⚠️ [Google Tracking] Warning messages (orange background)

GOOGLE.init({
    tagId: 'AW-XXXXX',
    debug: true,
});

📝 TypeScript Support

This package is written in TypeScript and bundles type definitions.

import type { GoogleTrackingConfig, ConversionParams } from '@adkit.so/google-tracking';

const config: GoogleTrackingConfig = {
    tagId: 'AW-XXXXX',
    debug: true,
};

const params: ConversionParams = {
    value: 100,
    currency: 'USD',
    transaction_id: 'order_123',
};

❓ Troubleshooting

Conversions not tracking?

1. Check your Tag ID - Make sure it's correct (format: AW-XXXXXXXXXX)
2. Check Conversion ID - Full format: AW-XXXXXXXXXX/CONVERSION_LABEL
3. Enable debug mode - Set debug: true in init() to see detailed logs
4. Check browser console - Look for errors or warnings
5. Check Ad Blockers - Ad blockers may block Google tracking scripts
6. Enable on localhost - Set enableLocalhost: true if testing locally

Conversions not showing in Google Ads?

• Wait up to 24 hours - Conversions can take time to appear
• Check Google Tag Assistant - Use the Chrome extension to verify tags
• Verify conversion action - Ensure the conversion is set up in Google Ads

📚 Official Documentation

Learn more about Google Ads conversion tracking:

• Google Ads Conversion Tracking - Getting started guide
• gtag.js Reference - Complete API reference
• Event Snippets - Conversion tracking setup
• Google Tag Assistant - Debug your tags

🔗 Related Packages

Check out our other tracking packages:

• Meta Pixel - @adkit.so/meta-pixel

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT

Made with ❤️ by AdKit

If this package helped you, please consider giving it a ⭐️ on GitHub!