Integrazione Google Ads Server-Side (SS) su piattaforma WEB

Introduzione

L’integrazione server-side (SS) di Google Ads rappresenta un salto di qualità rispetto alle tradizionali implementazioni client-side tramite tag o JavaScript. Dal punto di vista architetturale, consente un controllo più sicuro, affidabile e auditabile su tutte le conversioni inviate verso Google Ads.

Vantaggi principali

• Conformità GDPR: il tracciamento avviene lato server, riducendo la dipendenza da cookie e script di terze parti.
• Controllo e sicurezza: il tuo sistema, come per ERP (Xtumble) gestisce in prima persona gli eventi, evitando manomissioni o blocchi lato browser.
• Maggiore resilienza: le conversioni non vengono perse a causa di ad blocker o problemi JS lato client.

Requisiti iniziali

Per poter integrare Google Ads via API è necessario ottenere:

1. Un account Google Ads con accesso amministrativo o MCC
2. Un developer token approvato (non solo “test”):
   https://ads.google.com/aw/apicenter
3. Un progetto Google Cloud Console da cui ottenere:
   • client_id
   • client_secret
   • Importante: va abilitata la API di Google Ads:
     https://console.cloud.google.com/apis/library/googleads.googleapis.com
4. Scope OAuth richiesto:
   https://www.googleapis.com/auth/adwords

Cosa serve al cliente per fare l’onboarding

• Avere un account Google Ads attivo
• Avere accesso amministrativo all’account Google Ads (oppure essere collegato a un MCC)
• Essere in grado di effettuare il login a Google e accettare l’autorizzazione tramite finestra OAuth
• Confermare il consenso all’accesso per la piattaforma Xtumble

L’operazione non richiede particolari competenze tecniche e può essere completata in meno di 60 secondi.

Onboarding del cliente via OAuth2 (Authorization Code Flow)

Il cliente accede tramite browser a un URL come questo:

https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&response_type=code&scope=https://www.googleapis.com/auth/adwords&redirect_uri=https://your-platform.com/oauth2callback&access_type=offline&prompt=consent&state=SESSION_ID

Scambio code per token

curl -X POST https://oauth2.googleapis.com/token \
 -d "code=RECEIVED_CODE" \
 -d "client_id=YOUR_CLIENT_ID" \
 -d "client_secret=YOUR_CLIENT_SECRET" \
 -d "redirect_uri=https://your-platform.com/oauth2callback" \
 -d "grant_type=authorization_code"

Risposta:

{
  "access_token": "ya29...",
  "expires_in": 3599,
  "refresh_token": "1//0...",
  "scope": "https://www.googleapis.com/auth/adwords",
  "token_type": "Bearer"
}

Elenco conversion actions attive per un customer_id

curl -X POST \
  https://googleads.googleapis.com/v15/customers/6214438139/googleAds:search \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "developer-token: YOUR_DEV_TOKEN" \
  -H "login-customer-id: 6214438139" \
  -H "Content-Type: application/json" \
  -d '{
        "query": "SELECT conversion_action.id, conversion_action.name, conversion_action.status FROM conversion_action"
      }'

Esempio di invio di evento conversione (es. acquisto)

curl -X POST \
  https://googleads.googleapis.com/v15/customers/6214438139:uploadClickConversions \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "developer-token: YOUR_DEV_TOKEN" \
  -H "login-customer-id: 6214438139" \
  -H "Content-Type: application/json" \
  -d '{
        "conversions": [
          {
            "gclid": "EAIaIQobChMI...",
            "conversionAction": "customers/6214438139/conversionActions/9876543210",
            "conversionDateTime": "2025-06-18 16:45:00+02:00",
            "conversionValue": 89.90,
            "currencyCode": "EUR"
          }
        ],
        "partialFailure": true,
        "validateOnly": false
      }'

In una prossima revisione integreremo anche esempi in Delphi e un flusso completo multi-tenant con fallback automatico del access_token via refresh_token.

Autore: Ivan Revelli, CTO @ Synaptica SRL
Data: Giugno 2025