Invia eventi

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

I dati sugli eventi sono un'origine dati aggiuntiva per le conversioni dei tag, per massimizzare gli indicatori di interazione con gli annunci e rafforzare i dati e il rendimento complessivo.

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 degli 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 esito positivo e negativo.

Prepara una destinazione

Prima di poter inviare i dati, devi preparare la destinazione a cui inviarli. Ecco un Destination di esempio che puoi utilizzare:

    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }

• Imposta accountId di operatingAccount sull'ID account Google Ads che riceverà i dati sugli eventi. Il product di operatingAccount deve essere GOOGLE_ADS.

• Imposta productDestinationId sull'ID dell'azione di conversione per gli eventi. L'azione di conversione deve essere un'azione di conversione Google Ads con type impostato su WEBPAGE.

  Questa guida mostra come creare una richiesta che invia ogni evento alla stessa azione di conversione. Se vuoi inviare eventi per più azioni di conversione nella stessa richiesta, consulta 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.

Ecco i dati del primo evento:

Ecco i dati del secondo evento:

Formatta i dati

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

Ecco i dati del secondo evento dopo la formattazione:

Hashing e 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 del primo evento dopo la formattazione, l'hashing e la codifica utilizzando la codifica esadecimale:

Ecco i dati del secondo evento dopo la formattazione, l'hashing e la codifica utilizzando la codifica esadecimale:

Converti i dati in un Event

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

• event_timestamp: l'ora in cui si è verificato l'evento.
• transaction_id: l'identificatore univoco dell'evento.
• event_source: l'origine dell'evento. Se specificato, deve essere WEB.
• ad_identifiers o user_data: l'evento deve avere un identificatore pubblicitario o dati utente. Invia entrambi se li hai per l'evento.

Consulta la documentazione di riferimento Event per l'elenco completo dei campi disponibili. Compila tutti i campi in cui hai un valore per l'evento.

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

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "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"
            }
         }
      ]
   }
}

Crea il corpo della richiesta

Combina Destination e Events per il corpo della richiesta:

{
  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 1.99,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "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"
             }
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

1. Aggiorna i segnaposto nel corpo, ad esempio OPERATING_ACCOUNT_ID e CONVERSION_ACTION_1_ID con i valori del tuo account e della tua 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 questa richiesta 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. Vai alla pagina events.ingest.
3. Fai clic sul pulsante API a destra e poi sul pulsante Prova nella sezione espansa.
4. Incolla il corpo della richiesta copiato nella casella Corpo della richiesta.
5. Fai clic sul pulsante Esegui, completa le richieste di autorizzazione e rivedi la risposta.

Risposte riuscite

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

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

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 email_address contenente una stringa di testo normale anziché un valore codificato in 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 email_address 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 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": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "123456789"
      "reference": "conversion_action_1"
    },
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "777111122"
      "reference": "conversion_action_2"
    }
  ]

Imposta il destination_references di ogni Event per inviarlo a una o più destinazioni specifiche. Ad esempio, ecco un Event che riguarda solo il primo Destination, quindi il suo elenco destination_references 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": [
      "conversion_action_1"
   ]
}

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

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 di più sulle best practice.

• Scopri di più su limiti e quote.