Invia eventi

Puoi seguire questa guida rapida per acquisire familiarità con l'invio dei dati sugli eventi.

Utilizza l'API Data Manager per uno dei seguenti scenari:

• Invia le conversioni del tag Google Ads o gli eventi chiave di Google Analytics come un'origine dati aggiuntiva per le conversioni dei tag, in modo da massimizzare gli indicatori di interazione con gli annunci e rafforzare i dati e il rendimento complessivo.

  Questa funzionalità è disponibile solo per gli account in una lista consentita. Compila il modulo se ti interessa aggiungere il tuo account Google Ads o la tua proprietà Google Analytics.

• Invia i dati sugli eventi per le conversioni offline di Google Ads o le conversioni avanzate per i lead.

Scegli la versione della guida che vuoi visualizzare:

Inserzionista Partner di dati

In questa guida rapida, completerai i seguenti passaggi:

1. Prepara un Destination per ricevere i dati degli eventi.
2. Prepara i dati sugli eventi da inviare.
3. Crea una richiesta IngestionService per gli eventi.
4. Invia la richiesta con Explorer API di Google.
5. Comprendere le risposte di successo e di errore.

Preparare le destinazioni

Prima di poter inviare i dati, devi preparare almeno un Destination per i dati. Ecco un Destination di esempio che puoi utilizzare:

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID"
    }

Di seguito sono riportati i campi di un Destination:

operatingAccount

L'account che riceve gli eventi.

Per gli eventi inviati come origine dati aggiuntiva, l'account operativo può essere un account Google Ads o una proprietà Google Analytics. Imposta accountType su GOOGLE_ADS o GOOGLE_ANALYTICS_PROPERTY e accountId sull'ID cliente Google Ads o sull'ID proprietà Google Analytics. Se accountType è GOOGLE_ANALYTICS_PROPERTY, le credenziali della richiesta devono essere per un utente Google Analytics con il ruolo Editor o Amministratore per la proprietà.

Per le conversioni offline e le conversioni avanzate per i lead, l'account operativo deve essere un account Google Ads, quindi imposta accountType su GOOGLE_ADS e accountId sull'ID cliente Google Ads.

loginAccount

L'account a cui ha accesso l'utente delle credenziali.

Se le tue credenziali OAuth sono per un utente con accesso a un account amministratore Google Ads che ha operatingAccount come uno dei suoi subaccount, è necessario loginAccount. Imposta accountId di loginAccount sull'ID dell'account amministratore e imposta accountType di loginAccount su GOOGLE_ADS.

Se le tue credenziali OAuth sono per un utente con accesso diretto a operatingAccount, non devi impostare loginAccount e il valore predefinito è operatingAccount. Tuttavia, ti consigliamo di impostare loginAccount sullo stesso accountId e accountType di operatingAccount. In questo modo si evitano problemi se cambia l'insieme di account a cui l'utente può accedere.

productDestinationId

L'ID dell'entità in operatingAccount che riceve gli eventi.

Per gli eventi inviati come origine dati aggiuntiva, productDestinationId deve essere l'ID di una conversione Google Ads con type impostato su WEBPAGE o l'ID misurazione di uno stream web Google Analytics. Non puoi inviare eventi come origine dati aggiuntiva a uno stream di app per iOS o Android di Google Analytics.

Per le conversioni offline o le conversioni avanzate per i lead, il productDestinationId deve essere l'ID di un'azione di conversione Google Ads con type impostato su UPLOAD_CLICKS.

L'esempio in questa guida mostra come creare una richiesta che invia ogni evento alla stessa destinazione. Se vuoi inviare eventi per più destinazioni nella stessa richiesta, consulta Inviare eventi per più destinazioni.

Preparare i dati evento

Considera i seguenti dati sugli eventi. Ogni tabella corrisponde a un evento di conversione. Ogni evento di conversione ha un timestamp, l'azione di conversione e il valore di conversione.

Ogni evento potrebbe avere identificatori pubblicitari, come gclid, o identificatori utente, come indirizzi email, numeri di telefono e informazioni sull'indirizzo. Un evento può anche avere:

• Informazioni sull'utente valutate al momento dell'evento, ad esempio il valore del cliente o se è un cliente nuovo, di ritorno o riattivato.
• Dati del carrello.
• Parametri evento o proprietà utente aggiuntivi per una destinazione, ad esempio client_id o user_id per Google Analytics.

Ecco i dati dell'evento:

Formattare i dati

Formatta i campi come specificato nella guida alla formattazione. Ecco i dati dell'evento dopo la formattazione:

Esegui l'hashing e la codifica dei dati

Inoltre, gli indirizzi email, i nomi e i cognomi formattati devono essere sottoposti ad hashing utilizzando l'algoritmo SHA-256 e codificati utilizzando la codifica esadecimale o Base64. Ecco i dati evento dopo la formattazione, l'hashing e la codifica utilizzando la codifica esadecimale:

Converti i dati in oggetti Event

Converti i dati formattati e sottoposti ad hashing di ogni evento in un Event. Compila i seguenti campi come indicato:

1. Imposta eventTimestamp sull'ora in cui si è verificato l'evento.

   Gli eventi per Google Analytics devono avere un eventTimestamp nelle ultime 72 ore.

2. Imposta i campi obbligatori per il tuo caso d'uso.

   Caso d'uso	Identificatori	transactionId	eventSource
   Conversioni offline o conversioni avanzate per i lead	Required. Imposta almeno uno dei seguenti valori: adIdentifiers con almeno uno dei valori gclid, gbraid, wbraid o sessionAttributes impostato userData	Facoltativo	Required. Imposta uno dei valori enum per EventSource.
   Eventi inviati come origine dati aggiuntiva a una destinazione Google Ads	Required. Imposta almeno uno dei seguenti valori: adIdentifiers con almeno uno dei valori gclid, gbraid o wbraid impostato userData	Obbligatorio	Facoltativo. Se impostato, deve essere WEB.
   Eventi inviati come origine dati aggiuntiva a una destinazione Google Analytics	Required. Imposta almeno uno dei seguenti valori: clientId adIdentifiers con gclid impostato userData	Obbligatorio	Facoltativo. Se impostato, deve essere WEB.

3. Compila gli altri campi per i quali hai un valore per l'evento. Consulta la documentazione di riferimento Event per l'elenco completo dei campi disponibili.

Aggiungere informazioni su Google Analytics

Se le destinazioni di un evento inviato come origine dati aggiuntiva includono una proprietà Google Analytics, compila i seguenti campi come indicato:

eventName

Required. Il nome dell'evento Google Analytics.

transactionId

Obbligatorio . L'identificatore univoco dell'evento.

Almeno un identificatore

Deve essere impostato almeno uno dei seguenti campi:

• clientId: identificatore univoco per un'istanza utente di un client web. Consulta Invia un evento a Measurement Protocol.

• adIdentifiers.gclid: un ID clic Google.

• userData: identificatori dell'utente, come indirizzi email, numeri di telefono o informazioni sull'indirizzo.

destinationReferences

Obbligatorio se l'elenco destinations a livello di richiesta contiene più di un Destination Google Analytics. Aggiungi una voce a destinationReferences per specificare quale destinazione Google Analytics deve ricevere l'evento. Per saperne di più sui riferimenti alle destinazioni, consulta Inviare eventi a più destinazioni.

Se destinationReferences non è impostato o ha più voci che fanno riferimento a destinazioni Google Analytics, l'API Data Manager rifiuta l'evento con l'errore MULTIPLE_DESTINATIONS_FOR_GOOGLE_ANALYTICS_EVENT.

userId

Facoltativo. L'User-ID dell'utente.

additionalEventParameters

Facoltativo, ma consigliato. Compila questo elenco con tutti i parametri degli eventi Google Analytics che non vengono acquisiti negli altri campi Event. I parametri possono includere parametri aggiuntivi consigliati dell'evento purchase o altri parametri che vuoi acquisire. Utilizza il nome del parametro Google Analytics per parameterName di EventParameter.

Ad esempio, se hai le imposte associate a una transazione, aggiungi una voce a additionalEventParameters con parameterName impostato su tax e value impostato sul costo delle imposte.

Sconsigliamo di aggiungere voci per i parametri evento transactionId, currency o value di Google Analytics. Compila invece i campi transactionId, currency e conversionValue di Event, che hanno la precedenza su qualsiasi voce in additionalEventParameters.

Aggiungere i dati del carrello per gli eventi di acquisto

Compila il campo cartData di Event con le informazioni sugli articoli acquistati. Per ogni articolo acquistato, aggiungi un oggetto Item all'elenco items di CartData e compila i seguenti campi come indicato:

itemId

Obbligatorio. Un identificatore univoco per l'elemento.

unitPrice

Required. Il prezzo unitario al netto di tasse, spese di spedizione e sconti a livello di evento (a livello di transazione).

Se l'articolo ha uno sconto a livello di articolo, utilizza il prezzo unitario scontato. Ad esempio, se un articolo ha un prezzo unitario di 27.67 e uno sconto unitario di 6.66, imposta unitPrice su 21.01.

quantity

Required. La quantità di unità acquistate per questo articolo specifico.

additionalItemParameters

Compila questo elenco con tutti i parametri con ambito elemento che non vengono acquisiti negli altri campi Item. Utilizza il nome del parametro elemento Google Analytics per il parameterName di ItemParameter.

Ad esempio, se hai il brand e la categoria di un articolo, aggiungi una voce a additionalItemParameters dell'articolo con parameterName impostato su item_brand e value impostato sul nome del brand e un'altra voce con parameterName impostato su item_category e value impostato sulla categoria dell'articolo.

Non consigliamo di aggiungere voci per i parametri degli elementi quantity, price o item_id di Google Analytics. Compila invece i campi itemId, unitPrice e quantity di Item, che hanno la precedenza su qualsiasi voce in additionalItemParameters.

Ecco un Event di esempio per i dati formattati, sottoposti ad hashing e codificati del secondo evento, con dati aggiuntivi per Google Analytics:

{
  "adIdentifiers": {
     "gclid": "GCLID_2"
  },
  "conversionValue": 42.02,
  "currency": "EUR",
  "eventTimestamp": "2025-06-10T23:42:33-05:00",
  "transactionId": "DEF999911111",
  "eventSource": "WEB",
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
      },
      {
        "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
      },
      {
        "address": {
          "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
          "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
          "regionCode": "PT",
          "postalCode": "1229-076"
        }
      }
    ],
  },
  "userProperties": {
    "customerType": "RETURNING"
  },
  "eventName": "purchase",
  "clientId": "9876543210.1761582117",
  "userId": "user_DEF9876",
  "additionalEventParameters": [
    {
      "parameterName": "ad_unit_name",
      "value": "Banner_02"
    }
  ],
  "cartData": {
    "transactionDiscount": 6.66,
    "items": [
      {
        "itemId": "SKU_12346",
        "quantity": 2,
        "unitPrice": 21.01,
        "additionalItemParameters": [
          {
            "parameterName": "item_name",
            "value": "Google Grey Women's Tee"
          },
          {
            "parameterName": "affiliation",
            "value": "Google Merchandise Store"
          },
          {
            "parameterName": "coupon",
            "value": "SUMMER_FUN"
          },
          {
            "parameterName": "discount",
            "value": "3.33"
          },
          {
            "parameterName": "index",
            "value": "1"
          },
          {
            "parameterName": "item_brand",
            "value": "Google"
          },
          {
            "parameterName": "item_category",
            "value": "Apparel"
          },
          {
            "parameterName": "item_category2",
            "value": "Adult"
          },
          {
            "parameterName": "item_category3",
            "value": "Shirts"
          },
          {
            "parameterName": "item_category4",
            "value": "Crew"
          },
          {
            "parameterName": "item_category5",
            "value": "Short sleeve"
          },
          {
            "parameterName": "item_list_id",
            "value": "related_products"
          },
          {
            "parameterName": "item_list_name",
            "value": "Related Products"
          }
        ]
      }
    ]
  }
}

Crea il corpo della richiesta

Combina Destination e Events per il corpo della richiesta:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 30.03,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "NEW",
         "customerValueBucket": "HIGH"
       },
       "eventName": "purchase",
       "clientId": "1234567890.1761581763",
       "userId": "user_ABC12345",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_01"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12345",
             "quantity": 3,
             "unitPrice": 10.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Stan and Friends Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "2.22"
               },
               {
                 "parameterName": "index",
                 "value": "0"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]

       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 42.02,
       "currency": "EUR",
       "eventTimestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "RETURNING"
       },
       "eventName": "purchase",
       "clientId": "9876543210.1761582117",
       "userId": "user_DEF9876",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_02"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12346",
             "quantity": 2,
             "unitPrice": 21.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Google Grey Women's Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "3.33"
               },
               {
                 "parameterName": "index",
                 "value": "1"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

1. Aggiorna i segnaposto nel corpo, ad esempio OPERATING_ACCOUNT_ID e PRODUCT_DESTINATION_ID con i valori del tuo account e della destinazione.
2. Imposta validateOnly su true per convalidare la richiesta senza applicare le modifiche. Quando è tutto pronto per applicare le modifiche, imposta validateOnly su false.
3. Tieni presente che questo esempio non utilizza la crittografia.

Invia la richiesta

1. Copia il corpo della richiesta utilizzando il pulsante di copia in alto a destra nell'esempio.
2. Fai clic sul pulsante API nella barra degli strumenti.
3. Incolla il corpo della richiesta copiato nella casella Corpo della richiesta.
4. Fai clic sul pulsante Esegui, completa le richieste di autorizzazione ed esamina la risposta.

Risposte riuscite

Una richiesta riuscita restituisce una risposta con un oggetto contenente un requestId.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

Registra il requestId restituito in modo da poter recuperare la diagnostica man mano che ogni destinazione nella richiesta viene elaborata.

Risposte di errore

Una richiesta non riuscita genera un codice di stato di risposta di errore, ad esempio 400 Bad Request, e una risposta con i dettagli dell'errore.

Ad esempio, un emailAddress contenente una stringa di testo normale anziché un valore con codifica esadecimale produce la seguente risposta:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

Un emailAddress non sottoposto ad hashing e codificato solo in formato esadecimale produce la seguente risposta:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

Inviare eventi per più destinazioni

Se i tuoi dati contengono eventi per destinazioni diverse, puoi inviarli nella stessa richiesta utilizzando i riferimenti alle destinazioni.

Ad esempio, se hai un evento per l'ID azione di conversione 123456789 e un altro evento per l'ID azione di conversione 777111122, invia entrambi gli eventi in un'unica richiesta impostando reference di ogni Destination. Il reference è definito dall'utente. L'unico requisito è che ogni Destination abbia un reference univoco. Ecco l'elenco destinations modificato per la richiesta:

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID",
      "reference": "destination_a"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "777111122",
      "reference": "destination_b"
    }
  ]

Imposta il destinationReferences di ogni Event per inviarlo a una o più destinazioni specifiche. Ad esempio, ecco un Event valido solo per il primo Destination, quindi il suo elenco destinationReferences contiene solo il reference del primo Destination:

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "destination_a"
   ]
}

Il campo destinationReferences è un elenco, quindi puoi specificare più destinazioni per un evento. Se non imposti il destinationReferences di un Event, l'API Data Manager invia l'evento a tutte le destinazioni nella richiesta.

Se un evento ha più destinazioni, l'API Data Manager invia i campi pertinenti a ogni destinazione. Ad esempio, se un evento ha una destinazione Google Ads e una destinazione Google Analytics, l'API include campi Google Analytics come clientId o eventName quando invia l'evento alla destinazione Google Analytics e include campi Google Ads come customVariables quando invia l'evento alla destinazione Google Ads.

Passaggi successivi

• Configura l'autenticazione e configura il tuo ambiente con una libreria client.
• Scopri di più sui requisiti di formattazione, hashing e codifica per ogni tipo di dati.
• Scopri come criptare i dati utente.
• Scopri come recuperare i dati di diagnostica per le tue richieste.
• Scopri di più sulle best practice.
• Scopri di più su limiti e quote.