Google Ads Conversion Node for n8n

An advanced n8n community node for tracking conversions in Google Ads with comprehensive support for batch processing, enhanced conversions, privacy compliance, and production-grade error handling.

🌟 Key Features

🎯 Multiple Identification Methods

• GCLID: Standard Google Click ID conversion tracking
• Enhanced Conversions: Privacy-safe user data matching with automatic SHA-256 hashing
• GBRAID: iOS app install conversion tracking (iOS 14.5+)
• WBRAID: iOS web-to-app conversion tracking

🏢 Manager Account (MCC) Support

• Full MCC compatibility: Upload conversions to managed accounts
• Account type detection: Automatic switching between regular and manager accounts
• Managed account selection: Searchable dropdown with account details
• Correct authentication: Proper login-customer-id headers for MCC

⚡ High-Performance Batch Processing

• Process up to 2000 conversions per API call
• 3 processing modes: Partial Failure, Fail Fast, Continue on Error
• Real-time progress tracking and statistics
• Automatic batch size optimization (1-2000 range)

🔐 Privacy & Compliance

• GDPR/EEA compliance with consent management
• Automatic data hashing (SHA-256) for user identifiers
• Zero data retention - processed data never stored
• Privacy-first design with data minimization

🛡️ Enterprise-Grade Reliability

• Intelligent retry logic with exponential backoff and jitter
• Custom error classification for different failure types
• Rate limit handling with automatic throttling
• Comprehensive logging for monitoring and debugging

🎛️ Developer Experience

• Validation mode for testing without uploading data
• Debug mode with detailed request/response logging
• TypeScript implementation with full type safety
• Extensive documentation and examples

📦 Installation

Option 1: npm Installation (Recommended)

npm install @jaimeflneto/n8n-nodes-google-ads-conversion

Option 2: n8n Community Nodes

1. In n8n, go to Settings → Community Nodes
2. Enter: @jaimeflneto/n8n-nodes-google-ads-conversion
3. Click Install
4. Restart n8n

Option 3: Manual Installation

1. Download the latest release
2. Extract to your n8n custom nodes directory
3. Run npm install in the extracted directory
4. Restart n8n

🚀 Quick Start

1. Prerequisites

• Google Ads account with appropriate permissions
• Google Ads Developer Token (apply here)
• Google Cloud Project with Google Ads API enabled
• OAuth2 credentials (Client ID & Secret)
• For Manager Accounts (MCC): Access to managed accounts you want to track

2. Setup Credentials

1. In n8n, create a new Google Ads OAuth2 credential
2. Fill in your Developer Token and Customer ID (Manager account ID for MCC)
3. Add OAuth2 Client ID and Secret
4. Complete the authorization flow

3. Configure Node

Add the Google Ads Conversion node to your workflow and configure:

• Account Type: Choose Regular Account or Manager Account (MCC)
• Managed Account: Select target account (only for MCC)
• Conversion Action ID: From Google Ads conversion settings
• Identification Method: Choose GCLID, Enhanced, GBRAID, or WBRAID
• Conversion Data: Value, currency, timestamp, etc.

💡 Usage Examples

Basic GCLID Conversion

{
  "operation": "uploadClickConversion",
  "conversionAction": "customers/1234567890/conversionActions/987654321",
  "conversionDateTime": "2025-01-15 14:30:00+00:00",
  "conversionValue": 99.99,
  "currencyCode": "USD",
  "orderId": "order_12345",
  "identificationMethod": "gclid",
  "gclid": "Cj0KCQiA..."
}

Enhanced Conversion with Privacy Compliance

{
  "operation": "uploadClickConversion",
  "conversionAction": "customers/1234567890/conversionActions/987654321",
  "conversionDateTime": "2025-01-15 14:30:00+00:00",
  "conversionValue": 149.99,
  "currencyCode": "USD",
  "identificationMethod": "enhanced",
  "email": "[email protected]",
  "phoneNumber": "+1234567890",
  "firstName": "John",
  "lastName": "Doe",
  "adUserDataConsent": "GRANTED",
  "adPersonalizationConsent": "GRANTED"
}

Manager Account (MCC) Configuration

{
  "operation": "uploadClickConversion",
  "accountType": "manager",
  "managedAccount": {
    "mode": "list",
    "value": "9876543210"
  },
  "conversionAction": "customers/9876543210/conversionActions/987654321",
  "conversionDateTime": "{{$now}}",
  "conversionValue": 199.99,
  "currencyCode": "USD",
  "identificationMethod": "gclid",
  "gclid": "Cj0KCQiA..."
}

Batch Processing Configuration

{
  "enableBatchProcessing": true,
  "batchSize": 500,
  "batchProcessingMode": "partialFailure",
  "showProgress": true
}

📚 Documentation

• User Guide: Complete setup and usage instructions
• Developer Guide: Architecture and development details
• API Reference: Complete parameter reference
• Changelog: Version history and updates

🔧 Configuration Reference

Required Parameters

| Parameter | Description | Example | |-----------|-------------|---------| | conversionAction | Conversion action ID | customers/123/conversionActions/456 | | conversionDateTime | Conversion timestamp | 2025-01-15 14:30:00+00:00 or {{$now}} | | identificationMethod | User identification method | gclid, enhanced, gbraid, wbraid |

Account Configuration

| Parameter | Description | Example | |-----------|-------------|---------| | accountType | Account type | regular, manager | | managedAccount | Managed account (MCC only) | { "mode": "list", "value": "1234567890" } |

Optional Parameters

| Parameter | Description | Default | |-----------|-------------|---------| | conversionValue | Monetary value | 0 | | currencyCode | Currency code | USD | | orderId | Transaction ID | - | | validateOnly | Test mode | false | | debugMode | Debug logging | false |

Batch Processing

| Parameter | Description | Default | |-----------|-------------|---------| | enableBatchProcessing | Enable batch mode | false | | batchSize | Items per batch | 100 | | batchProcessingMode | Error handling mode | partialFailure | | showProgress | Progress logging | true |

🧪 Testing

Automated Tests

npm test

Validation Mode

Enable validateOnly to test configurations without uploading data to Google Ads.

Debug Mode

Enable debugMode for comprehensive logging of requests, responses, and processing details.

🐛 Troubleshooting

Common Issues

Authentication Errors

• Verify developer token is approved and active
• Check OAuth2 credentials are correctly configured
• Ensure customer ID format is correct (123-456-7890)
• For MCC: Verify manager account has access to selected managed account

Validation Errors

• Verify all required fields are provided
• Check date format: YYYY-MM-DD HH:MM:SS+TZ or use {{$now}}
• For enhanced conversions, provide at least one user identifier
• For MCC: Ensure managed account is selected when using manager account type

Rate Limiting

• Enable batch processing for high volumes
• Node automatically handles retries with exponential backoff
• Monitor Google Ads API quotas

Debug Information

Enable debug mode to see:

• Request payloads and headers
• Response data and status codes
• Retry attempts and delays
• Error details with stack traces

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

git clone https://github.com/jaimeneot85/n8n-nodes-google-ads-conversion.git
cd n8n-nodes-google-ads-conversion
npm install
npm run dev

Code Standards

• TypeScript with strict type checking
• ESLint for code quality
• Prettier for formatting
• SOLID principles and DRY implementation

📊 Performance

Batch Processing Benefits

• Up to 2000x reduction in API calls
• Improved throughput for large datasets
• Reduced rate limiting exposure
• Better resource utilization

Memory Efficiency

• Streaming batch processing
• No data persistence
• Optimized memory usage for large datasets

🔒 Security & Privacy

Data Protection

• Zero data retention: No conversion data stored
• Secure transmission: HTTPS-only communication
• Credential security: OAuth2 with token refresh
• Automatic hashing: SHA-256 for user identifiers

Privacy Compliance

• GDPR support: Comprehensive consent handling
• Data minimization: Only required fields processed
• User control: Configurable consent levels
• Audit trail: Comprehensive logging

📈 Roadmap

✅ Recently Implemented (v0.7.0)

• Manager Account (MCC) Support: Full support for uploading conversions to managed accounts
• DateTime Object Support: Native compatibility with n8n {{$now}} expressions
• Enhanced Error Handling: Improved URL validation and customer ID processing

Upcoming Features

• Offline conversion support
• Bulk conversion import
• Analytics integration
• Custom audience support
• Advanced attribution models

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Support

• Documentation: User Guide | Developer Guide
• Issues: GitHub Issues
• Community: n8n Community Forum
• Email: [email protected]

🙏 Acknowledgments

• n8n.io for the amazing workflow automation platform
• Google Ads API for comprehensive conversion tracking
• The n8n community for feedback and contributions

Made with ❤️ by Jaime Lima Neto

If this project helps your business, consider sponsoring me to support continued development.