Google Ads Enhanced Conversions API: Server-Side Tracking Setup Guide 2026

// Node.js Beispiel für Conversion Endpoint
const express = require('express');
const crypto = require('crypto');
const { GoogleAdsApi } = require('google-ads-api');

app.post('/conversion', async (req, res) => {
  try {
    const { email, phone, value, orderId } = req.body;
    
    // Hash customer data
    const hashedEmail = hashData(email);
    const hashedPhone = hashData(phone);
    
    // Send to Google Ads API
    await sendConversion({
      hashedEmail,
      hashedPhone,
      conversionValue: value,
      orderId
    });
    
    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Conversion error:', error);
    res.status(500).json({ error: error.message });
  }
});

function hashData(data) {
  return crypto.createHash('sha256')
    .update(data.toLowerCase().trim())
    .digest('hex');
}

<?php
require_once 'vendor/autoload.php';

use Google\Ads\GoogleAds\GoogleAdsClient;
use Google\Ads\GoogleAds\V14\Services\ConversionUploadServiceClient;
use Google\Ads\GoogleAds\V14\Common\UserIdentifier;
use Google\Ads\GoogleAds\V14\Services\ClickConversion;

class EnhancedConversionsAPI {
    private $client;
    private $customerId;
    
    public function __construct($customerId) {
        $this->client = GoogleAdsClient::fromFile();
        $this->customerId = $customerId;
    }
    
    public function sendConversion($conversionData) {
        $conversionUploadService = $this->client
            ->getConversionUploadServiceClient();
        
        $clickConversion = new ClickConversion();
        $clickConversion->setConversionAction(
            'customers/' . $this->customerId . '/conversionActions/' . 
            $conversionData['conversionActionId']
        );
        
        // Hash customer data
        $hashedEmail = $this->hashUserData($conversionData['email']);
        $hashedPhone = $this->hashUserData($conversionData['phone']);
        
        $userIdentifier1 = new UserIdentifier();
        $userIdentifier1->setHashedEmail($hashedEmail);
        
        $userIdentifier2 = new UserIdentifier();
        $userIdentifier2->setHashedPhoneNumber($hashedPhone);
        
        $clickConversion->setUserIdentifiers([
            $userIdentifier1, 
            $userIdentifier2
        ]);
        
        $clickConversion->setConversionValue($conversionData['value']);
        $clickConversion->setCurrencyCode('EUR');
        $clickConversion->setConversionDateTime(
            date('Y-m-d H:i:s', $conversionData['timestamp'])
        );
        
        try {
            $response = $conversionUploadService->uploadClickConversions(
                $this->customerId, 
                [$clickConversion]
            );
            
            return $response;
        } catch (Exception $e) {
            error_log('Enhanced Conversions API Error: ' . $e->getMessage());
            throw $e;
        }
    }
    
    private function hashUserData($data) {
        return hash('sha256', strtolower(trim($data)));
    }
}
?>

from flask import Flask, request, jsonify
import hashlib
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.v14.services.types.conversion_upload_service import UploadClickConversionsRequest
from google.ads.googleads.v14.common.types.offline_user_data import UserIdentifier
from google.ads.googleads.v14.services.types.conversion_upload_service import ClickConversion

app = Flask(__name__)

class EnhancedConversionsHandler:
    def __init__(self, customer_id):
        self.client = GoogleAdsClient.load_from_storage()
        self.customer_id = customer_id
        
    def hash_user_data(self, data):
        return hashlib.sha256(data.lower().strip().encode()).hexdigest()
        
    def send_conversion(self, conversion_data):
        conversion_upload_service = self.client.get_service(
            "ConversionUploadService"
        )
        
        click_conversion = ClickConversion()
        click_conversion.conversion_action = (
            f"customers/{self.customer_id}/conversionActions/"
            f"{conversion_data['conversion_action_id']}"
        )
        
        # Create user identifiers
        email_identifier = UserIdentifier()
        email_identifier.hashed_email = self.hash_user_data(
            conversion_data['email']
        )
        
        phone_identifier = UserIdentifier()
        phone_identifier.hashed_phone_number = self.hash_user_data(
            conversion_data['phone']
        )
        
        click_conversion.user_identifiers.extend([
            email_identifier, 
            phone_identifier
        ])
        
        click_conversion.conversion_value = conversion_data['value']
        click_conversion.currency_code = 'EUR'
        click_conversion.conversion_date_time = conversion_data['timestamp']
        
        try:
            request = UploadClickConversionsRequest()
            request.customer_id = self.customer_id
            request.conversions.append(click_conversion)
            request.partial_failure = True
            
            response = conversion_upload_service.upload_click_conversions(
                request=request
            )
            
            return response
            
        except Exception as e:
            print(f"Enhanced Conversions API Error: {e}")
            raise

@app.route('/conversion', methods=['POST'])
def handle_conversion():
    try:
        data = request.get_json()
        handler = EnhancedConversionsHandler('YOUR_CUSTOMER_ID')
        result = handler.send_conversion(data)
        
        return jsonify({
            'success': True,
            'partial_failure_error': str(result.partial_failure_error)
        })
        
    except Exception as e:
        return jsonify({
            'success': False,
            'error': str(e)
        }), 500

if __name__ == '__main__':
    app.run(debug=False, host='0.0.0.0', port=5000)

const express = require('express');
const crypto = require('crypto');
const { GoogleAdsApi, enums } = require('google-ads-api');

const app = express();
app.use(express.json());

class EnhancedConversionsManager {
    constructor(customerId, credentials) {
        this.customerId = customerId;
        this.client = new GoogleAdsApi({
            client_id: credentials.client_id,
            client_secret: credentials.client_secret,
            developer_token: credentials.developer_token
        });
        
        this.customer = this.client.Customer({
            customer_id: customerId,
            refresh_token: credentials.refresh_token
        });
    }
    
    hashUserData(data) {
        return crypto.createHash('sha256')
            .update(data.toLowerCase().trim())
            .digest('hex');
    }
    
    async uploadConversion(conversionData) {
        try {
            const userIdentifiers = [];
            
            if (conversionData.email) {
                userIdentifiers.push({
                    hashed_email: this.hashUserData(conversionData.email)
                });
            }
            
            if (conversionData.phone) {
                userIdentifiers.push({
                    hashed_phone_number: this.hashUserData(conversionData.phone)
                });
            }
            
            const clickConversion = {
                conversion_action: `customers/${this.customerId}/conversionActions/${conversionData.conversionActionId}`,
                conversion_date_time: conversionData.timestamp,
                conversion_value: conversionData.value,
                currency_code: 'EUR',
                user_identifiers: userIdentifiers,
                order_id: conversionData.orderId || null
            };
            
            const response = await this.customer.conversionUploads.uploadClickConversions({
                conversions: [clickConversion],
                partial_failure: true
            });
            
            return response;
            
        } catch (error) {
            console.error('Enhanced Conversions Upload Error:', error);
            throw error;
        }
    }
}

// Initialize manager
const conversionManager = new EnhancedConversionsManager(
    process.env.GOOGLE_ADS_CUSTOMER_ID,
    {
        client_id: process.env.GOOGLE_ADS_CLIENT_ID,
        client_secret: process.env.GOOGLE_ADS_CLIENT_SECRET,
        developer_token: process.env.GOOGLE_ADS_DEVELOPER_TOKEN,
        refresh_token: process.env.GOOGLE_ADS_REFRESH_TOKEN
    }
);

app.post('/api/conversion', async (req, res) => {
    try {
        const { email, phone, value, orderId, conversionActionId } = req.body;
        
        // Validate required fields
        if (!conversionActionId || !value) {
            return res.status(400).json({
                error: 'Missing required fields: conversionActionId, value'
            });
        }
        
        if (!email && !phone) {
            return res.status(400).json({
                error: 'At least one user identifier (email or phone) required'
            });
        }
        
        const conversionData = {
            email,
            phone,
            value: parseFloat(value),
            orderId,
            conversionActionId,
            timestamp: new Date().toISOString()
        };
        
        const result = await conversionManager.uploadConversion(conversionData);
        
        res.json({
            success: true,
            result: result,
            message: 'Conversion uploaded successfully'
        });
        
    } catch (error) {
        console.error('Conversion API Error:', error);
        res.status(500).json({
            success: false,
            error: error.message
        });
    }
});

// Health check endpoint
app.get('/health', (req, res) => {
    res.json({ status: 'healthy', timestamp: new Date().toISOString() });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Enhanced Conversions API Server running on port ${PORT}`);
});

// Beispiel für Error Tracking und Alerting
class ConversionMonitor {
    constructor() {
        this.errorCounts = new Map();
        this.alertThresholds = {
            'AUTHENTICATION_ERROR': 1,
            'RATE_LIMIT_ERROR': 5,
            'CONVERSION_ACTION_NOT_FOUND': 3
        };
    }
    
    logError(errorType, error) {
        const count = this.errorCounts.get(errorType) || 0;
        this.errorCounts.set(errorType, count + 1);
        
        // Log to file/database
        console.error(`[${new Date().toISOString()}] ${errorType}: ${error.message}`);
        
        // Check if alert threshold is reached
        if (count + 1 >= (this.alertThresholds[errorType] || 10)) {
            this.sendAlert(errorType, count + 1);
        }
    }
    
    sendAlert(errorType, count) {
        // Send to monitoring service (Slack, email, etc.)
        const alertMessage = `🚨 Enhanced Conversions API Alert: ${errorType} occurred ${count} times`;
        
        // Example: Send to Slack webhook
        fetch(process.env.SLACK_WEBHOOK_URL, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ text: alertMessage })
        });
    }
    
    getHealthStatus() {
        const totalErrors = Array.from(this.errorCounts.values())
            .reduce((sum, count) => sum + count, 0);
            
        return {
            status: totalErrors < 10 ? 'healthy' : 'degraded',
            totalErrors,
            errorBreakdown: Object.fromEntries(this.errorCounts)
        };
    }
}

class ConversionBatchProcessor {
    constructor(batchSize = 100, flushInterval = 5000) {
        this.batchSize = batchSize;
        this.flushInterval = flushInterval;
        this.conversionQueue = [];
        this.isProcessing = false;
        
        // Auto-flush every 5 seconds
        setInterval(() => this.flush(), this.flushInterval);
    }
    
    addConversion(conversionData) {
        this.conversionQueue.push(conversionData);
        
        // Flush if batch size is reached
        if (this.conversionQueue.length >= this.batchSize) {
            this.flush();
        }
    }
    
    async flush() {
        if (this.isProcessing || this.conversionQueue.length === 0) {
            return;
        }
        
        this.isProcessing = true;
        const batch = this.conversionQueue.splice(0, this.batchSize);
        
        try {
            await this.processBatch(batch);
            console.log(`Successfully processed batch of ${batch.length} conversions`);
        } catch (error) {
            console.error('Batch processing error:', error);
            // Re-queue failed conversions for retry
            this.conversionQueue.unshift(...batch);
        } finally {
            this.isProcessing = false;
        }
    }
    
    async processBatch(conversions) {
        const clickConversions = conversions.map(conv => ({
            conversion_action: `customers/${this.customerId}/conversionActions/${conv.actionId}`,
            conversion_value: conv.value,
            conversion_date_time: conv.timestamp,
            user_identifiers: conv.userIdentifiers,
            order_id: conv.orderId
        }));
        
        return await this.customer.conversionUploads.uploadClickConversions({
            conversions: clickConversions,
            partial_failure: true
        });
    }
}

class PrivacyCompliantConversions {
    constructor() {
        this.consentStatus = new Map();
        this.dataRetentionPeriod = 365 * 24 * 60 * 60 * 1000; // 365 days
    }
    
    checkConsent(userId) {
        const consent = this.consentStatus.get(userId);
        
        if (!consent) {
            return false;
        }
        
        // Check if consent is still valid (not expired)
        const now = new Date().getTime();
        return consent.timestamp + this.dataRetentionPeriod > now;
    }
    
    processConversionWithConsent(conversionData) {
        const { userId, email, phone } = conversionData;
        
        // Check consent before processing
        if (!this.checkConsent(userId)) {
            console.log(`Skipping conversion for user ${userId} - no valid consent`);
            return { success: false, reason: 'no_consent' };
        }
        
        // Anonymize data before hashing
        const sanitizedData = this.sanitizeUserData({
            email: email?.toLowerCase().trim(),
            phone: phone?.replace(/[^+\d]/g, '')
        });
        
        return this.sendConversion({
            ...conversionData,
            ...sanitizedData
        });
    }
    
    sanitizeUserData(userData) {
        const sanitized = {};
        
        // Only include data if present and valid
        if (userData.email && this.isValidEmail(userData.email)) {
            sanitized.hashedEmail = this.hashData(userData.email);
        }
        
        if (userData.phone && this.isValidPhone(userData.phone)) {
            sanitized.hashedPhone = this.hashData(userData.phone);
        }
        
        return sanitized;
    }
    
    handleOptOut(userId) {
        // Remove user from enhanced conversions
        this.consentStatus.delete(userId);
        
        // Log opt-out for audit purposes
        console.log(`User ${userId} opted out of enhanced conversions at ${new Date().toISOString()}`);
        
        // Optional: Delete historical data
        this.deleteUserConversionHistory(userId);
    }
    
    isValidEmail(email) {
        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
        return emailRegex.test(email);
    }
    
    isValidPhone(phone) {
        const phoneRegex = /^\+[1-9]\d{1,14}$/;
        return phoneRegex.test(phone);
    }
}

// Beispiel für CookieBot Integration
window.addEventListener('CookiebotOnConsentReady', function() {
    if (Cookiebot.consent.marketing) {
        // User has consented to marketing cookies
        enableEnhancedConversions();
    } else {
        // User has not consented
        disableEnhancedConversions();
    }
});

function enableEnhancedConversions() {
    window.enhancedConversionsEnabled = true;
    console.log('Enhanced Conversions enabled based on user consent');
}

function disableEnhancedConversions() {
    window.enhancedConversionsEnabled = false;
    console.log('Enhanced Conversions disabled - no marketing consent');
}

// Check consent before sending conversion
function sendConversionWithConsentCheck(conversionData) {
    if (!window.enhancedConversionsEnabled) {
        console.log('Skipping enhanced conversion - no consent');
        return;
    }
    
    // Proceed with conversion tracking
    sendEnhancedConversion(conversionData);
}

// Jest Unit Tests für Enhanced Conversions
const { hashUserData, normalizeUserData } = require('./conversions');

describe('Enhanced Conversions Utils', () => {
    describe('normalizeUserData', () => {
        test('should normalize email to lowercase and trim', () => {
            const input = '  John@Example.COM  ';
            const expected = 'john@example.com';
            expect(normalizeUserData.email(input)).toBe(expected);
        });
        
        test('should normalize phone number with country code', () => {
            const input = '+49 (123) 456-7890';
            const expected = '+491234567890';
            expect(normalizeUserData.phone(input)).toBe(expected);
        });
        
        test('should handle invalid email formats', () => {
            const input = 'invalid-email';
            expect(() => normalizeUserData.email(input)).toThrow();
        });
    });
    
    describe('hashUserData', () => {
        test('should create consistent SHA-256 hash', () => {
            const input = 'john@example.com';
            const hash1 = hashUserData(input);
            const hash2 = hashUserData(input);
            
            expect(hash1).toBe(hash2);
            expect(hash1).toHaveLength(64); // SHA-256 produces 64-char hex string
        });
        
        test('should create different hashes for different inputs', () => {
            const hash1 = hashUserData('john@example.com');
            const hash2 = hashUserData('jane@example.com');
            
            expect(hash1).not.toBe(hash2);
        });
    });
    
    describe('API Request Validation', () => {
        test('should validate required fields', () => {
            const validData = {
                conversionActionId: '123',
                conversionValue: 99.99,
                userIdentifiers: [{ hashedEmail: 'hash123' }],
                timestamp: new Date().toISOString()
            };
            
            expect(validateConversionData(validData)).toBe(true);
        });
        
        test('should reject invalid conversion values', () => {
            const invalidData = {
                conversionActionId: '123',
                conversionValue: -10, // Negative values not allowed
                userIdentifiers: [{ hashedEmail: 'hash123' }]
            };
            
            expect(() => validateConversionData(invalidData)).toThrow();
        });
    });
});

// Integration Test Beispiel
const request = require('supertest');
const app = require('./app');

describe('Enhanced Conversions API Integration', () => {
    let testCustomerId;
    let testConversionActionId;
    
    beforeAll(async () => {
        // Setup test environment
        testCustomerId = process.env.TEST_CUSTOMER_ID;
        testConversionActionId = await createTestConversionAction();
    });
    
    afterAll(async () => {
        // Cleanup test data
        await cleanupTestConversions();
    });
    
    test('should successfully upload conversion via API endpoint', async () => {
        const conversionData = {
            email: 'test@example.com',
            phone: '+49123456789',
            value: 49.99,
            currency: 'EUR',
            conversionActionId: testConversionActionId,
            orderId: `test-order-${Date.now()}`
        };
        
        const response = await request(app)
            .post('/api/conversion')
            .send(conversionData)
            .expect(200);
            
        expect(response.body.success).toBe(true);
        expect(response.body.result).toBeDefined();
        
        // Verify conversion was actually sent to Google Ads
        const uploadedConversions = await verifyConversionUpload(
            testCustomerId, 
            conversionData.orderId
        );
        
        expect(uploadedConversions.length).toBe(1);
    });
    
    test('should handle partial failures gracefully', async () => {
        const conversionsWithErrors = [
            { /* valid conversion */ },
            { /* invalid conversion - missing required field */ },
            { /* another valid conversion */ }
        ];
        
        const response = await request(app)
            .post('/api/conversions/batch')
            .send({ conversions: conversionsWithErrors })
            .expect(200);
            
        expect(response.body.partialFailures).toBeDefined();
        expect(response.body.successCount).toBe(2);
        expect(response.body.failureCount).toBe(1);
    });
    
    test('should respect rate limits', async () => {
        const promises = [];
        
        // Send many requests simultaneously
        for (let i = 0; i < 20; i++) {
            promises.push(
                request(app)
                    .post('/api/conversion')
                    .send(generateTestConversion())
            );
        }
        
        const results = await Promise.allSettled(promises);
        
        // Some requests should succeed, some might be rate limited
        const successes = results.filter(r => r.status === 'fulfilled' && r.value.status === 200);
        const rateLimited = results.filter(r => r.status === 'fulfilled' && r.value.status === 429);
        
        expect(successes.length + rateLimited.length).toBe(20);
        expect(rateLimited.length).toBeGreaterThan(0); // Rate limiting should kick in
    });
});