Enviar eventos

Você pode usar este guia de início rápido para se familiarizar com o envio de dados de eventos.

Os dados de eventos são uma fonte adicional para as conversões da sua tag, maximizando os indicadores de interação com o anúncio e fortalecendo seus dados e a performance geral.

Escolha a versão do guia que você quer acessar:

Neste guia de início rápido, você vai concluir as seguintes etapas:

  1. Prepare um Destination para receber dados de eventos.
  2. Prepare os dados de eventos para envio.
  3. Crie uma solicitação IngestionService para eventos.
  4. Envie a solicitação com o Google APIs Explorer.
  5. Entenda as respostas de sucesso e falha.

Preparar um destino

Antes de enviar dados, é preciso preparar o destino para onde eles serão enviados. Confira um exemplo de Destination para usar:

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

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  • Defina o accountId do operatingAccount como o ID da conta do Google Ads que vai receber os dados de evento. O product do operatingAccount precisa ser GOOGLE_ADS.

  • Defina o productDestinationId como o ID da ação de conversão para os eventos. A ação de conversão precisa ser do Google Ads com type definido como WEBPAGE.

    Este guia mostra como criar uma solicitação que envia todos os eventos para a mesma ação de conversão. Se quiser enviar eventos para várias ações de conversão na mesma solicitação, consulte vários destinos.

Preparar dados de eventos

Considere os seguintes dados de evento. Cada tabela corresponde a um evento de conversão. Cada evento de conversão tem um carimbo de data/hora, uma ação e um valor.

Cada evento pode ter identificadores de publicidade, como gclid, ou de usuário, como endereços de e-mail, números de telefone e informações de endereço.

Confira os dados do primeiro evento:

Evento nº 1
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 1.99
currency USD
gclid GCLID_1
emails
given_name John
last_name Smith-Jones
region_code us
postal_code 94045

Confira os dados do segundo evento:

Evento 2
conversion_time June 10, 2025 11:42:33PM America/New_York
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 3.25
currency eur
gclid GCLID_2
emails

zoe@EXAMPLE.COM

cloudy.sanfrancisco@gmail.com
given_name zoë
last_name pérez
region_code PT
postal_code 1229-076

Formatar os dados

Formate os campos conforme especificado no guia de formatação. Estes são os dados do primeiro evento após a formatação:

Evento nº 1
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 1.99
currency USD
gclid GCLID_1
emails
given_name john
last_name smith-jones
region_code US
postal_code 94045

Estes são os dados do segundo evento após a formatação:

Evento 2
conversion_time 2025-06-10T23:42:33-05:00
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 3.25
currency EUR
gclid GCLID_2
emails

zoe@example.com

cloudysanfrancisco@gmail.com
given_name zoë
last_name pérez
region_code PT
postal_code 1229-076

Gerar hash e codificar os dados

Além disso, os endereços de e-mail, nomes e sobrenomes formatados precisam ser criptografados com hash usando o algoritmo SHA-256 e codificados usando hexadecimal ou Base64. Estes são os dados do primeiro evento após formatação, hash e codificação usando codificação hexadecimal:

Evento nº 1
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 1.99
currency USD
gclid GCLID_1
emails
given_name 96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A
last_name DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081
region_code US
postal_code 94045

Aqui estão os dados do segundo evento após formatação, hash e codificação usando codificação hexadecimal:

Evento 2
conversion_time 2025-06-10T23:42:33-05:00
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 3.25
currency EUR
gclid GCLID_2
emails

3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250

223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4
given_name 2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450
last_name 6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F
region_code PT
postal_code 1229-076

Converter os dados em um Event

Converter os dados formatados e com hash de cada evento em um Event. Preencha os seguintes campos obrigatórios:

  • timestamp: o horário em que o evento ocorreu.
  • transaction_id: o identificador exclusivo do evento.
  • event_source: a origem do evento. Se especificado, precisa ser EVENT_SOURCE_WEB.
  • ad_identifiers ou user_data: o evento precisa ter um identificador de publicidade ou dados do usuário. Envie os dois se você tiver os dois para o evento.

Consulte a documentação de referência Event para ver a lista completa de campos disponíveis. Preencha todos os campos em que você tem um valor para o evento.

Confira um exemplo de Event para os dados formatados, com hash e codificados do segundo evento:

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "currency": "EUR",
   "timestamp": "2025-06-10T23:42:33-05:00",
   "transactionId": "DEF999911111",
   "eventSource": "EVENT_SOURCE_WEB",
   "userData": {
      "userIdentifiers": [
         {
            "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
         },
         {
            "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
         },
         {
            "address": {
              "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
              "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
              "regionCode": "PT",
              "postalCode": "1229-076"
            }
         }
      ]
   }
}

Criar o corpo da solicitação

Combine Destination e Events no corpo da solicitação:

{
  "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",
       "timestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "EVENT_SOURCE_WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "lastName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "currency": "EUR",
       "timestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "EVENT_SOURCE_WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "lastName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       }
     }
  ],
  "validateOnly": true
}
  1. Atualize os marcadores no corpo, como OPERATING_ACCOUNT_ID e CONVERSION_ACTION_1_ID com os valores da sua conta e destino.
  2. Defina validateOnly como true para validar a solicitação sem aplicar as mudanças. Quando estiver tudo pronto para aplicar as mudanças, defina validateOnly como false.
  3. Essa solicitação não usa criptografia.

Enviar a solicitação

  1. Copie o corpo da solicitação usando o botão de cópia no canto superior direito da amostra.
  2. Acesse a página events.ingest.
  3. Clique no botão API à direita e depois no botão Faça um teste na seção expandida.
  4. Cole o corpo da solicitação copiado na caixa Corpo da solicitação.
  5. Clique no botão Executar, preencha as solicitações de autorização e revise a resposta.

Respostas de sucesso

Uma solicitação bem-sucedida retorna uma resposta com um objeto que contém um requestId.

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

Respostas de falha

Uma solicitação com falha resulta em um código de status de resposta de erro, como 400 Bad Request, e uma resposta com detalhes do erro.

Por exemplo, um email_address que contém uma string de texto simples em vez de um valor codificado em hexadecimal produz a seguinte resposta:

{
  "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"
          }
        ]
      }
    ]
  }
}

Um email_address que não é hash e é codificado apenas em hexadecimal produz a seguinte resposta:

{
  "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"
          }
        ]
      }
    ]
  }
}

Enviar eventos para vários destinos

Se os dados tiverem eventos para destinos diferentes, você poderá enviá-los na mesma solicitação usando referências de destino.

Por exemplo, se você tiver um evento para o ID da ação de conversão 123456789 e outro para o ID 777111122, envie os dois eventos em uma única solicitação definindo o reference de cada Destination. O reference é definido pelo usuário. O único requisito é que cada Destination tenha um reference exclusivo. Esta é a lista destinations modificada para a solicitação:

  "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"
    }
  ]

Defina o destination_references de cada Event para enviar a um ou mais destinos específicos. Por exemplo, este é um Event que é apenas para o primeiro Destination. Portanto, a lista destination_references contém apenas o reference do primeiro Destination:

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

O campo destination_references é uma lista. Portanto, é possível especificar vários destinos para um evento. Se você não definir o destination_references de um Event, a API Data Manager vai enviar o evento para todos os destinos na solicitação.

Próximas etapas