Mapeamento de especificação da ECAPI

Este guia ajuda os desenvolvedores que usam a especificação da API Event and Conversion (ECAPI) do IAB Tech Lab a mapear os dados de eventos e conversões para o esquema de ingestão de eventos da API Data Manager.

Visão geral

A ECAPI é um padrão de dados de código aberto, independente de plataforma, que define a estrutura de eventos e conversões relacionados ao marketing.

A tabela a seguir mostra uma visão geral de como os principais atributos e princípios de design da ECAPI se comparam à API Data Manager:

	ECAPI	API Data Manager
Eliminação de duplicação	Depende de id (ID do evento)	Depende de transaction_id
Roteamento de eventos	O campo data_set_id no payload do evento indica o destino dos dados.	O campo destinations da solicitação define os destinos dos eventos. A API Data Manager também permite rotear eventos para vários destinos em uma única solicitação. Consulte Configurar destinos e cabeçalhos para mais informações.
Campos de privacidade e consentimento	Strings de consentimento da Plataforma de Privacidade Global (GPP)	A API Data Manager não aceita nem analisa strings de consentimento da Plataforma de Privacidade Global (GPP). Defina os campos de consentimento no objeto Consent. É possível definir o consentimento no nível da solicitação (que se aplica a todos os eventos na solicitação) ou no nível do evento (que permite especificar diferentes configurações de consentimento para eventos individuais).

Mapeamento de campo estrutural

As tabelas de mapeamento a seguir definem como os campos individuais da especificação da ECAPI são traduzidos em campos aceitos pela API Data Manager:

Dica: consulte a Visão geral de eventos para começar a enviar eventos e saber mais sobre os campos obrigatórios e opcionais de cada caso de uso de ingestão de eventos.

Mapeamento de objetos de evento

ECAPI (event)	API Data Manager (Event)	Observações
data_set_id	destinations[].product_destination_id (nível de solicitação) destination_references (nível do evento)	É possível definir destinos nos seguintes níveis: Nível da solicitação (obrigatório): especifique a lista de destinations no IngestEventsRequest. Nível do evento (opcional): use o campo destination_references no objeto Event. Adicione uma entrada para especificar qual destino da lista destinations deve receber o evento. Para mais informações sobre como definir um Destination e determinar o ID de destino do produto, consulte Configurar destinos e cabeçalhos.
id	transaction_id	Elimina a duplicação de eventos de conversão. Consulte Como o Google lida com dados de várias fontes nos guias Enviar eventos do Google Ads, do Google Analytics e do Floodlight.
timestamp	event_timestamp	Obrigatório. A ECAPI usa o formato de época Unix (número inteiro) para carimbos de data/hora. Ao mapear para a API Data Manager, converta o campo event_timestamp em um dos seguintes formatos: Se estiver usando o formato JSON, defina um valor no formato RFC 3339. Se estiver usando buffers de protocolo, use um Timestamp e defina os campos seconds e (opcionalmente) nanoseconds. Consulte Formato de carimbo de data/hora para mais detalhes.
event_type / custom_event	event_name	Pode ser um nome de evento recomendado (por exemplo, purchase) ou personalizado. Consulte Nomes de eventos padrão para mais detalhes.
user_data	user_data	Mapeia para o objeto UserData, que aceita uma lista de objetos UserIdentifier.
value	conversion_value	Mapeie diretamente como um valor duplo ou flutuante que representa o valor monetário da conversão.
currency_code	currency	Mapeie para um código de moeda de três letras maiúsculas (por exemplo, USD).
source	event_source	Defina como um valor do tipo enumerado EventSource.
properties	cart_data custom_variables additional_event_parameters	Mapeie os itens no nível da transação para a matriz cart_data.items no objeto CartData. A API Data Manager é compatível com vários campos opcionais do Merchant Center para produtos que existem em contas do Merchant Center. Se o destino for uma ação de conversão do Google Ads, você também poderá incluir outros parâmetros personalizados no campo custom_variables como uma lista de objetos CustomVariable. Se o destino for um fluxo de dados do Google Analytics, inclua outros parâmetros de evento no campo additional_event_parameters como uma lista de objetos AdditionalEventParameter.
ext	Não há equivalente

Mapeamento de objetos de dados do usuário

Dica: consulte a seção Converter os dados em objetos Event nos guias Enviar eventos específicos do destino (disponíveis na Visão geral dos eventos para Google Ads, Google Analytics e Floodlight) para mais informações sobre quais identificadores são obrigatórios e recomendados para cada destino e caso de uso.

Na API Data Manager, o campo user_data no objeto Event aceita um objeto UserData. Isso espera uma lista de objetos UserIdentifier, que podem conter identificadores de usuário individuais, como endereços de e-mail, números de telefone ou componentes de endereço:

ECAPI (user_data)	API Data Manager (Event)	Observações
customer_identifier	user_id (Google Analytics)	Para eventos do Google Analytics, o campo user_id representa um User-ID. A API Data Manager não é compatível com campos genéricos de ID de cliente para outros destinos.
uids	Não há equivalente	A API Data Manager não é compatível com uma matriz uids estruturada que contém tipos de agentes e domínios.
customer_segments	user_properties	Mapeie para UserProperties no Event.
email_address	user_data.user_identifiers[].email_address	Defina como o endereço de e-mail formatado e com hash. Também é possível criptografar o endereço de e-mail com hash.
phone_numbers	user_data.user_identifiers[].phone_number	Defina como o número de telefone formatado e com hash. Também é possível criptografar o número de telefone com hash.
utcoffset	Não há equivalente	Se você estiver usando o formato JSON, poderá especificar o deslocamento de fuso horário diretamente na string RFC 3339 event_timestamp. Se você estiver usando buffers de protocolo, use funções utilitárias como Timestamps.parse(String) para processar a conversão de fuso horário em segundos e nanossegundos. Consulte o formato do carimbo de data/hora para mais detalhes.
address	user_data.user_identifiers[].address	Associa a um objeto AddressInfo. Consulte Mapeamento de objetos de endereço.
gpp_string	Não há equivalente	Mapeie o consentimento para o objeto Consent no nível do evento ou da solicitação. Consulte a Visão geral de privacidade e consentimento.
gpp_sid	Não há equivalente	Mapeie o consentimento para o objeto Consent no nível do evento ou da solicitação. Consulte a Visão geral de privacidade e consentimento.
mmt_only	Não há equivalente
click_id	ad_identifiers.gclid	Mapeie para o ID de clique do Google (gclid). Consulte AdIdentifiers para mais detalhes.
impression_id	ad_identifiers.impression_id	Consulte AdIdentifiers para mais detalhes.
event_ip_address	event_device_info.ip_address	Consulte DeviceInfo para ver os campos disponíveis.
event_user_agent	event_device_info.user_agent	Consulte DeviceInfo para ver os campos disponíveis.
ifa	ad_identifiers.mobile_device_id	Mapeie para o identificador de publicidade para dispositivos móveis (IDFA no iOS, AdID no Android). Consulte AdIdentifiers para mais detalhes.
landing_ip_address	ad_identifiers.landing_page_device_info.ip_address	Consulte DeviceInfo para ver os campos disponíveis.
landing_user_agent	ad_identifiers.landing_page_device_info.user_agent	Consulte DeviceInfo para ver os campos disponíveis.
age_range	Não há equivalente
gender	Não há equivalente
ext	Não há equivalente

Mapeamento de objetos de endereço

ECAPI (address)	API Data Manager (AddressInfo)	Observações
first_name	given_name	Mapeia para o campo given_name em AddressInfo. Siga as diretrizes de formatação e hash. Também é possível criptografar os atributos com hash de um endereço.
last_name	family_name	Mapeia para o campo family_name em AddressInfo. Siga as diretrizes de formatação e hash. Também é possível criptografar os atributos com hash de um endereço.
street	Não há equivalente	Não há suporte na API Data Manager.
city	Não há equivalente	Não há suporte na API Data Manager.
state	Não há equivalente	Não há suporte na API Data Manager.
country_code	region_code	Não use hash. Mapeia para o campo region_code em AddressInfo. Siga as diretrizes de formatação.
postal_code	postal_code	Não use hash. Mapeia para o campo postal_code em AddressInfo. Siga as diretrizes de formatação.
address_type	Não há equivalente	Não há suporte na API Data Manager.
ext	Não há equivalente

Mapeamento de objetos de itens

Dica: consulte a seção Adicionar dados do carrinho nos guias Enviar eventos específicos do destino (disponíveis na Visão geral dos eventos para Google Ads, Google Analytics e Floodlight) para mais informações sobre quais campos incluir nos dados do carrinho para cada caso de uso de ingestão de eventos.

ECAPI (item)	API Data Manager (Item)	Observações
id	item_id	Obrigatório para eventos do Google Analytics. Defina um identificador padrão e exclusivo para o item.
Não há equivalente	merchant_product_id	Obrigatório para conversões do Floodlight e do Google Ads com dados do carrinho. Defina como o ID do produto na conta do Merchant Center.
name	additional_item_parameters	Mapeie como item_name na lista additional_item_parameters.
price	unit_price
discount	additional_item_parameters ou custom_variables	Mapeie como discount no additional_item_parameters (para o Google Analytics) ou como uma variável personalizada no custom_variables (para o Google Ads).
quantity	quantity	Converta o valor float em um número inteiro (int64).
brand	additional_item_parameters	Mapeie como item_brand na lista additional_item_parameters.
affiliation	additional_item_parameters	Mapeie como affiliation na lista additional_item_parameters.
category	additional_item_parameters	Mapeie como item_category na lista additional_item_parameters.
cattax	Não há equivalente
item_coupon	additional_item_parameters	Mapeie como coupon na lista additional_item_parameters.
item_list_id	additional_item_parameters	Mapeie como item_list_id na lista additional_item_parameters.
item_list_name	additional_item_parameters	Mapeie como item_list_name na lista additional_item_parameters.
item_item_variant	additional_item_parameters	Mapeie como item_variant na lista additional_item_parameters.
item_location_id	additional_item_parameters	Mapear como location_id em additional_item_parameters.
ext	Não há equivalente

Nomes de eventos padrão

Os eventos padrão da ECAPI estão totalmente alinhados às convenções de nomenclatura do Google Analytics.

• Se você estiver enviando eventos para um fluxo de dados do Google Analytics, o campo event_name será obrigatório.

• Consulte a referência de eventos recomendados do Google Analytics para conhecer os campos, parâmetros e exemplos de solicitações de ingestão da API Data Manager para cada evento.

• Também é possível enviar eventos personalizados, desde que eles sigam as regras de nomenclatura de eventos.

A maioria dos eventos padrão da ECAPI (como purchase, add_to_cart, begin_checkout, search e refund) tem o mesmo nome que os eventos recomendados do Google Analytics. No entanto, há algumas exceções em que o Google Analytics usa o presente em vez do passado:

• viewed_item mapeia para view_item

• viewed_item_list mapeia para view_item_list

• viewed_cart mapeia para view_cart

Exemplos de solicitação

As guias a seguir mostram uma comparação entre um payload de evento de conversão da ECAPI e a representação dele como um IngestEventsRequest válido da API Data Manager:

ECAPI

Veja um exemplo de payload JSON que segue a especificação da ECAPI:

{
  "data_set_id": "123456789",
  "id": "ABC798654321",
  "timestamp": 1781035621,
  "event_type": "purchase",
  "value": 30.03,
  "currency_code": "USD",
  "source": "website",
  "user_data": {
    "customer_identifier": "123456789123456789",
    "customer_segments": ["gold_member"],
    "email_addresses": [
      "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
    ],
    "address": {
      "first_name": "96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a",
      "last_name": "db98d2607efffa28aff66975868bf54c075eca7157e35064dce08e20b85b1081",
      "country_code": "US",
      "postal_code": "94045"
    },
    "event_ip_address": "192.0.2.1",
    "event_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
  },
  "properties": {
    "items": [
      {
        "id": "SKU_12345",
        "quantity": 3,
        "item_price": 10.01
      }
    ]
  }
}

API Data Manager

Veja um exemplo de IngestEventsRequest para os dados de eventos formatados, com hash e codificados. O tipo de conta GOOGLE_ADS no destino indica que a solicitação é direcionada a um destino do Google Ads:

{
  "destinations": [
    {
      "operating_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "login_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "product_destination_id": "123456789"
    }
  ],
  "encoding": "HEX",
  "events": [
    {
      "event_name": "purchase",
      "transaction_id": "ABC798654321",
      "event_timestamp": "2026-06-10T20:07:01Z",
      "event_source": "WEB",
      "user_properties": {
        "additional_user_properties":[
          {
            "property_name": "customer_segment",
            "value": "gold_member"
          }
        ]
      },
      "user_data": {
        "user_identifiers": [
          {
            "email_address": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
          },
          {
            "address": {
              "given_name": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
              "family_name": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
              "region_code": "US",
              "postal_code": "94045"
            }
          }
        ]
      },
      "event_device_info": {
        "ip_address": "192.0.2.1",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
      },
      "conversion_value": 30.03,
      "currency": "USD",
      "cart_data": {
        "items": [
          {
            "item_id": "SKU_12345",
            "quantity": 3,
            "unit_price": 10.01
          }
        ]
      }
    }
  ]
}