Description
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
- 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
- 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)
- 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
- 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
- Validation mode for testing without uploading data
- Debug mode with detailed request/response logging
- TypeScript implementation with full type safety
- Extensive documentation and examples
🏢 Manager Account (MCC) Support
⚡ High-Performance Batch Processing
🔐 Privacy & Compliance
🛡️ Enterprise-Grade Reliability
🎛️ Developer Experience
📦 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
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:
💡 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": "user@example.com",
"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
🔧 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
#### Validation Errors
YYYY-MM-DD HH:MM:SS+TZ or use {{$now}}#### Rate Limiting
Debug Information
Enable debug mode to see:
🤝 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
📊 Performance
Batch Processing Benefits
Memory Efficiency
🔒 Security & Privacy
Data Protection
Privacy Compliance
📈 Roadmap
✅ Recently Implemented (v0.7.0)
{{$now}} expressionsUpcoming Features
📝 License
This project is licensed under the MIT License – see the LICENSE file for details.
💬 Support
🙏 Acknowledgments
—
Made with ❤️ by Jaime Lima Neto
If this project helps your business, consider sponsoring me to support continued development.
