Mapeamento de especificação da ECAPI

Este guia ajuda os desenvolvedores que usam a especificação da API de eventos e conversões do IAB Tech Lab (ECAPI) 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 criado para definir como eventos e conversões relacionados a marketing são estruturados.

A tabela a seguir oferece 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 destino dos dados é indicado pelo campo data_set_id no payload do evento.	O campo destinations da solicitação define os destinos dos eventos. A API Data Manager também permite encaminhar eventos para vários destinos em uma única solicitação. Consulte o guia de destinos 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). Os campos de consentimento precisam ser definidos 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 o guia de envio 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 da solicitação) destination_references (nível do evento)	Pode ser definido nos seguintes níveis: Nível da solicitação (obrigatório): especifique a lista de destinations no IngestEventsRequest. Nível do evento: use o campo destination_references no objeto Event. Adicione uma entrada para especificar qual destino da lista destinations vai 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	Esse valor é usado para eliminar a duplicação de eventos de conversão. Saiba mais.
timestamp	event_timestamp	Obrigatório. A ECAPI usa o formato de época do Unix (inteiro) para carimbos de data/hora. Ao mapear para a API Data Manager, o campo event_timestamp precisa ser convertido em um dos seguintes formatos: Se você estiver usando o formato JSON, defina um valor no formato RFC 3339. Se você estiver usando buffers de protocolo, use um Timestamp e defina os campos seconds e (opcionalmente) nanoseconds. Consulte Formato do carimbo de data/hora para mais detalhes.
event_type / custom_event	event_name	Pode ser um nome de evento recomendado (por exemplo, purchase) ou um nome de evento 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 double ou float que representa o valor monetário da conversão.
currency_code	currency	Mapeie para um código de moeda de três letras em maiúsculas (por exemplo, USD).
source	event_source	Definido como um valor da enumeração EventSource.
properties	cart_data custom_variables additional_event_parameters	Os itens no nível da transação podem ser mapeados 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 parâmetros personalizados adicionais 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 do Guia de envio de eventos para mais informações sobre quais identificadores são necessá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ários 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 oferece suporte a campos genéricos de ID do cliente para outros destinos.
uids	Não há equivalente	A API Data Manager não é compatível com uma matriz uids estruturada que contenha tipos de agentes e domínios.
customer_segments	user_properties	Mapa para UserProperties no Event.
email_address	user_data.user_identifiers[].email_address	Definido 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	Definido 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, especifique o ajuste de fuso horário diretamente na string event_timestamp da RFC 3339. 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 Formato do carimbo de data/hora para mais detalhes.
address	user_data.user_identifiers[].address	Mapeia para um objeto AddressInfo. Consulte Mapeamento de objetos de endereço.
gpp_string	Não há equivalente	O consentimento precisa ser mapeado para o objeto Consent no nível da solicitação ou do evento. Confira a visão geral de privacidade e consentimento.
gpp_sid	Não há equivalente	O consentimento precisa ser mapeado para o objeto Consent no nível da solicitação ou do evento. Confira 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 conferir os campos disponíveis.
event_user_agent	event_device_info.user_agent	Consulte DeviceInfo para conferir os campos disponíveis.
ifa	ad_identifiers.mobile_device_id	Mapeie para o ID de publicidade móvel para anunciantes (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 conferir os campos disponíveis.
landing_user_agent	ad_identifiers.landing_page_device_info.user_agent	Consulte DeviceInfo para conferir 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 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 hash de um endereço.
street	Não há equivalente	Indisponível na API Data Manager
city	Não há equivalente	Indisponível na API Data Manager
state	Não há equivalente	Indisponível na API Data Manager
country_code	region_code	Não faça hash. Mapeia para o campo region_code em AddressInfo. Siga as diretrizes de formatação.
postal_code	postal_code	Não faça hash. Mapeia para o campo postal_code em AddressInfo. Siga as diretrizes de formatação.
address_type	Não há equivalente	Indisponível na API Data Manager
ext	Não há equivalente

Mapeamento de objetos de itens

Dica: consulte a seção Adicionar dados do carrinho no guia de envio de eventos para mais informações sobre quais campos incluir nos dados do carrinho em 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. Definido como um identificador padrão e exclusivo do item.
Não há equivalente	merchant_product_id	Obrigatório para conversões do Floodlight e do Google Ads com dados do carrinho. Definido 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 em additional_item_parameters (para o Google Analytics) ou como uma variável personalizada em custom_variables (para o Google Ads).
quantity	quantity	Converta o valor float em um número inteiro (int64).
brand	additional_item_parameters	Mapear 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	Mapa 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 muito 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.
• Confira a referência de eventos recomendados do Google Analytics para campos, parâmetros e exemplos de solicitações de ingestão da API Data Manager associados a cada evento.
• Também é possível enviar eventos personalizados, desde que 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 dos eventos recomendados do Google Analytics. No entanto, há algumas exceções em que o Google Analytics usa o tempo presente em vez do passado:

• viewed_item é mapeado para view_item
• viewed_item_list é mapeado para view_item_list
• viewed_cart é mapeado 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

Confira um exemplo de payload JSON em conformidade com 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

Confira um exemplo de IngestEventsRequest para os dados de eventos formatados, com hash e codificados. Isso é para um destino do Google Ads, conforme indicado pelo tipo de conta GOOGLE_ADS no destino.

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