Esta página foi traduzida pela API Cloud Translation.

Enviar eventos

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

Use a API Data Manager em um dos seguintes cenários:

Envie conversões da tag do Google Ads ou eventos principais do Google Analytics como uma fonte de dados adicional para as conversões da tag. Assim, você maximiza os indicadores de interação com o anúncio e fortalece seus dados e a performance geral.

Esse recurso está disponível apenas para contas em uma lista de permissões. Preencha o formulário se quiser adicionar sua conta do Google Ads ou propriedade do Google Analytics.

Observação: os dados da fonte extra que você conectar não serão transferidos para seus lances com base em conversão por 14 dias, que é o período de teste. Isso não se aplica à fonte de dados usada na tag do Google.
Envie dados de eventos para conversões off-line ou conversões otimizadas para leads do Google Ads.

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 destinos

Antes de enviar dados, é necessário preparar pelo menos um Destination para eles. Confira um exemplo de Destination para usar:

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

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

      "productDestinationId": "PRODUCT_DESTINATION_ID"
    }

Estes são os campos de um Destination:

operatingAccount

A conta que recebe os eventos.

Para eventos enviados como uma fonte de dados adicional, a conta operacional pode ser uma conta do Google Ads ou uma propriedade do Google Analytics. Defina accountType como GOOGLE_ADS ou GOOGLE_ANALYTICS_PROPERTY e accountId como o ID de cliente do Google Ads ou o ID da propriedade do Google Analytics. Se o accountType for GOOGLE_ANALYTICS_PROPERTY, as credenciais da solicitação precisarão ser de um usuário do Google Analytics com a função de editor ou administrador na propriedade.

Para conversões off-line e conversões otimizadas para leads, a conta operacional precisa ser do Google Ads. Portanto, defina accountType como GOOGLE_ADS e accountId como o ID do cliente do Google Ads.

loginAccount

A conta em que o usuário da credencial tem acesso.

Se as credenciais do OAuth forem de um usuário com acesso a uma conta de administrador do Google Ads que tenha operatingAccount como uma das subcontas, loginAccount será obrigatório. Defina a accountId da loginAccount como o ID da conta de administrador e defina a accountType da loginAccount como GOOGLE_ADS.

Se as credenciais do OAuth forem de um usuário com acesso direto ao operatingAccount, não será necessário definir loginAccount, e o padrão será o operatingAccount. No entanto, recomendamos definir loginAccount como o mesmo accountId e accountType do operatingAccount. Isso ajuda a evitar problemas se o conjunto de contas a que o usuário tem acesso mudar.

productDestinationId

O ID da entidade no operatingAccount que recebe os eventos.

Para eventos enviados como uma fonte de dados adicional, o productDestinationId precisa ser o ID de uma conversão do Google Ads com type definido como WEBPAGE ou o ID de métricas de um fluxo da Web do Google Analytics. Não é possível enviar eventos como uma fonte de dados adicional para um fluxo de app iOS ou Android do Google Analytics.

Para conversões off-line ou otimizadas para leads, o productDestinationId precisa ser o ID de uma ação de conversão do Google Ads com type definido como UPLOAD_CLICKS.

O exemplo neste guia mostra como construir uma solicitação que envia todos os eventos para o mesmo destino. Se quiser enviar eventos para vários destinos na mesma solicitação, consulte Enviar eventos para 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 identificadores de usuário, como endereços de e-mail, números de telefone e informações de endereço. Um evento também pode ter:

Informações sobre o usuário avaliado no momento do evento, como o valor do cliente ou se ele é novo, recorrente ou reengajado.
Dados do carrinho de compras.
Outros parâmetros de evento ou propriedades do usuário para um destino, como client_id ou user_id para o Google Analytics.

Confira os dados do evento:

Evento 1

Evento nº 1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`John`
`family_name`	`Smith-Jones`
`region_code`	`us`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
Itens no carrinho
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

Evento 2

Evento 2
`conversion_time`	`June 10, 2025 11:42:33PM America/New_York`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`eur`
`gclid`	`GCLID_2`
`emails`	`zoe@EXAMPLE.COM` `cloudy.sanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
Itens no carrinho
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

Formatar os dados

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

Evento 1

Evento nº 1
`conversion_time`	`2025-06-10T15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`john`
`family_name`	`smith-jones`
`region_code`	`US`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
Itens no carrinho
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

Evento 2

Evento 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`zoe@example.com` `cloudysanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
Itens no carrinho
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

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 de evento após formatação, hash e codificação usando codificação hexadecimal:

Evento 1

Evento nº 1
`conversion_time`	`2025-06-10T15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A`
`family_name`	`DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081`
`region_code`	`US`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
Itens no carrinho
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

Evento 2

Evento 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250` `223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4`
`given_name`	`2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450`
`family_name`	`6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
Itens no carrinho
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

Converter os dados em objetos `Event`

Converta os dados formatados e com hash de cada evento em um Event. Preencha os seguintes campos conforme indicado:

Defina eventTimestamp como o horário em que o evento ocorreu.

Os eventos do Google Analytics precisam ter um eventTimestamp nas últimas 72 horas.

Defina os campos obrigatórios para seu caso de uso.

Caso de uso	Identificadores	`transactionId`	`eventSource`
Conversões off-line ou conversões otimizadas para leads	Obrigatório. Defina pelo menos uma das seguintes opções: `adIdentifiers` com pelo menos um dos campos `gclid`, `gbraid`, `wbraid` ou `sessionAttributes` definido `userData`	Opcional	Obrigatório. Defina como um dos valores de enumeração para `EventSource`.
Eventos enviados como uma fonte de dados adicional para um destino do Google Ads	Obrigatório. Defina pelo menos uma das seguintes opções: `adIdentifiers` com pelo menos um de `gclid`, `gbraid` ou `wbraid` definido `userData`	Obrigatório	Opcional. Se definido, precisa ser `WEB`.
Eventos enviados como uma fonte de dados adicional para um destino do Google Analytics	Obrigatório. Defina pelo menos uma das seguintes opções: `clientId` `adIdentifiers` com `gclid` definido `userData`	Obrigatório	Opcional. Se definido, precisa ser `WEB`.

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

Adicionar informações do Google Analytics

Se os destinos de um evento enviado como uma fonte de dados adicional incluírem uma propriedade do Google Analytics, preencha os seguintes campos conforme indicado:

eventName

Obrigatório. O nome do evento do Google Analytics.

transactionId

Obrigatório . O identificador exclusivo do evento.

Pelo menos um identificador

É necessário definir pelo menos um dos campos a seguir:

clientId: identificador exclusivo de uma instância de usuário de um cliente da Web. Consulte Enviar evento para o Measurement Protocol.
adIdentifiers.gclid: um ID de clique do Google.
userData: identificadores do usuário, como endereços de e-mail, números de telefone ou informações de endereço.

destinationReferences

Obrigatório se a lista destinations no nível da solicitação contiver mais de um Destination do Google Analytics. Adicione uma entrada a destinationReferences para especificar qual destino do Google Analytics deve receber o evento. Consulte enviar eventos para vários destinos para mais informações sobre referências de destino.

Se destinationReferences não estiver definido ou tiver várias entradas que se referem a destinos do Google Analytics, a API Data Manager vai rejeitar o evento com o erro MULTIPLE_DESTINATIONS_FOR_GOOGLE_ANALYTICS_EVENT.

userId

Opcional. O User-ID do usuário.

additionalEventParameters

Opcional, mas recomendado. Preencha essa lista com todos os parâmetros de evento do Google Analytics que não são capturados nos outros campos Event. Os parâmetros podem incluir outros parâmetros recomendados do evento purchase ou outros que você queira capturar. Use o nome do parâmetro do Google Analytics para o parameterName do EventParameter.

Por exemplo, se você tiver os tributos associados a uma transação, adicione uma entrada a additionalEventParameters com parameterName definido como tax e value definido como o custo dos tributos.

Não recomendamos adicionar entradas para os parâmetros de evento do Google Analytics transactionId, currency ou value. Em vez disso, preencha transactionId, currency e conversionValue do Event, que têm precedência sobre todas as entradas em additionalEventParameters.

Adicionar dados do carrinho aos eventos de compra

Preencha o campo cartData do Event com informações sobre os itens comprados. Para cada item comprado, adicione um objeto Item à lista items do CartData e preencha os seguintes campos conforme indicado:

itemId

Obrigatório. Um identificador exclusivo do item.

unitPrice

Obrigatório. O preço unitário, sem tributos, frete e descontos no escopo do evento (no nível da transação).

Se o item tiver um desconto no escopo do item, use o preço unitário com desconto. Por exemplo, se um item tiver um preço unitário de 27.67 e um desconto unitário de 6.66, defina unitPrice como 21.01.

quantity

Obrigatório. A quantidade de unidades compradas para este item específico.

additionalItemParameters

Preencha essa lista com todos os parâmetros no escopo do item que não são capturados nos outros campos Item. Use o nome do parâmetro de item do Google Analytics para o parameterName do ItemParameter.

Por exemplo, se você tiver a marca e a categoria de um item, adicione uma entrada ao additionalItemParameters do item com parameterName definido como item_brand e value definido como o nome da marca. Adicione outra entrada com parameterName definido como item_category e value definido como a categoria do item.

Não recomendamos adicionar entradas para os parâmetros de item do Google Analytics quantity, price ou item_id. Em vez disso, preencha os campos itemId, unitPrice e quantity do Item, que têm precedência sobre todas as entradas em additionalItemParameters.

Confira um exemplo de Event para os dados formatados, com hash e codificados do segundo evento, com dados adicionais para o 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"
          }
        ]
      }
    ]
  }
}

Criar o corpo da solicitação

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

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

Atualize os marcadores no corpo, como OPERATING_ACCOUNT_ID e PRODUCT_DESTINATION_ID com os valores da sua conta e destino.
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.
Este exemplo 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.
Clique no botão API na barra de ferramentas.
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"
}

Registre o requestId retornado para recuperar diagnósticos à medida que cada destino na solicitação é processado.

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

Defina o destinationReferences 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 destinationReferences contém apenas o reference do primeiro Destination:

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

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

Se um evento tiver vários destinos, a API do Gerenciador de dados enviará os campos relevantes para cada um deles. Por exemplo, se um evento tiver um destino do Google Ads e outro do Google Analytics, a API vai incluir campos do Google Analytics, como clientId ou eventName, ao enviar o evento para o destino do Google Analytics, e campos do Google Ads, como customVariables, ao enviar o evento para o destino do Google Ads.

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 do usuário.
Saiba como recuperar diagnósticos para suas solicitações.
Saiba mais sobre as práticas recomendadas.
Saiba mais sobre limites e cotas.

Visão geral dos eventos

Enviar eventos Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Preparar destinos

Preparar dados de eventos

Evento 1

Evento 2

Formatar os dados

Evento 1

Evento 2

Gerar hash e codificar os dados

Evento 1

Evento 2

Converter os dados em objetos Event

Adicionar informações do Google Analytics

Adicionar dados do carrinho aos eventos de compra

Criar o corpo da solicitação

Enviar a solicitação

Respostas de sucesso

Respostas de falha

Enviar eventos para vários destinos

Próximas etapas

Enviar eventos

Converter os dados em objetos `Event`