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:
- Prepare um
Destination
para receber dados de eventos. - Prepare os dados de eventos para envio.
- Crie uma solicitação
IngestionService
para eventos. - Envie a solicitação com o Google APIs Explorer.
- 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
dooperatingAccount
como o ID da conta do Google Ads que vai receber os dados de evento. Oproduct
dooperatingAccount
precisa serGOOGLE_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 comtype
definido comoWEBPAGE
.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 |
|
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 |
|
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 |
|
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 serEVENT_SOURCE_WEB
.ad_identifiers
ouuser_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
}
- Atualize os marcadores no corpo, como
OPERATING_ACCOUNT_ID
eCONVERSION_ACTION_1_ID
com os valores da sua conta e destino. - Defina
validateOnly
comotrue
para validar a solicitação sem aplicar as mudanças. Quando estiver tudo pronto para aplicar as mudanças, definavalidateOnly
comofalse
. - Essa solicitação não usa criptografia.
Enviar a solicitação
- Copie o corpo da solicitação usando o botão de cópia no canto superior direito da amostra.
- Acesse a página
events.ingest
. - Clique no botão API à direita e depois no botão Faça um teste na seção expandida.
- Cole o corpo da solicitação copiado na caixa Corpo da solicitação.
- 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
- Configure a autenticação e configure seu ambiente com uma biblioteca de cliente.
- Saiba mais sobre os requisitos de formatação, hash e codificação para cada tipo de dado.
- Saiba como criptografar dados de usuários.