Asignación de especificaciones de la ECAPI

Esta guía ayuda a los desarrolladores que usan la especificación de la API de Eventos y Conversiones (ECAPI) del IAB Tech Lab a asignar sus datos de eventos y conversiones al esquema de transferencia de eventos de la API de Data Manager.

Descripción general

La ECAPI es un estándar de datos de código abierto independiente de la plataforma diseñado para definir cómo se estructuran los eventos y las conversiones relacionados con el marketing.

En la siguiente tabla, se proporciona una vista de alto nivel de cómo se comparan los atributos clave y los principios de diseño de la API de ECAPI con la API de Data Manager.

	ECAPI	API de Data Manager
Anulación de duplicación	Depende de id (ID del evento)	Depende de transaction_id
Enrutamiento de eventos	El campo data_set_id en la carga útil del evento indica el destino de los datos.	El campo destinations de la solicitud define los destinos de los eventos. La API de Data Manager también admite el enrutamiento de eventos a varios destinos en una sola solicitud. Consulta la guía de destinos para obtener más información.
Campos de privacidad y consentimiento	Cadenas de consentimiento de Global Privacy Platform (GPP)	La API de Data Manager no acepta ni analiza cadenas de consentimiento de la Plataforma de Privacidad Global (GPP). Los campos de consentimiento se deben establecer en el objeto Consent. Puedes establecer el consentimiento a nivel de la solicitud (que se aplica a todos los eventos de la solicitud) o a nivel del evento (que te permite especificar diferentes parámetros de configuración del consentimiento para eventos individuales).

Asignación de campos estructurales

En las siguientes tablas de asignación, se define cómo se traducen los campos individuales de la especificación de la ECAPI a los campos que acepta la API de Data Manager.

Sugerencia: Consulta la guía para enviar eventos y comenzar a enviar eventos, y obtén más información sobre los campos obligatorios y opcionales para cada caso de uso de la transferencia de eventos.

Asignación de objetos de eventos

ECAPI (event)	API de Data Manager (Event)	Notas
data_set_id	destinations[].product_destination_id (nivel de la solicitud) destination_references (a nivel del evento)	Se puede definir en los siguientes niveles: Nivel de solicitud (obligatorio): Especifica la lista de destinations en IngestEventsRequest. A nivel del evento: Usa el campo destination_references del objeto Event. Agrega una entrada para especificar qué destino de la lista destinations debe recibir el evento. Para obtener más información sobre cómo definir un Destination y determinar el ID del destino del producto, consulta Configura destinos y encabezados.
id	transaction_id	Este valor se usa para anular la duplicación de los eventos de conversión. Obtén más información.
timestamp	event_timestamp	Obligatorio. La ECAPI usa el formato de época de Unix (número entero) para las marcas de tiempo. Cuando se asigna a la API de Data Manager, el campo event_timestamp debe convertirse a uno de los siguientes formatos: Si usas el formato JSON, establece un valor en formato RFC 3339. Si usas búferes de protocolo, usa un Timestamp y configura los campos seconds y (opcionalmente) nanoseconds. Consulta Formato de marca de tiempo para obtener más detalles.
event_type/custom_event	event_name	Puede ser un nombre de evento recomendado (por ejemplo, purchase) o un nombre de evento personalizado. Consulta Nombres de eventos estándar para obtener más detalles.
user_data	user_data	Se asigna al objeto UserData, que acepta una lista de objetos UserIdentifier.
value	conversion_value	Se asigna directamente como un valor doble o flotante que representa el valor monetario de la conversión.
currency_code	currency	Se asigna a un código de moneda de tres letras en mayúsculas (por ejemplo, USD).
source	event_source	Se establece en un valor del enum EventSource.
properties	cart_data custom_variables additional_event_parameters	Los elementos a nivel de la transacción se pueden asignar al array cart_data.items en el objeto CartData. La API de Data Manager admite varios campos opcionales de Merchant Center para los productos que existen en las cuentas de Merchant Center. Si tu destino es una acción de conversión de Google Ads, también puedes incluir parámetros personalizados adicionales en el campo custom_variables como una lista de objetos CustomVariable. Si tu destino es un flujo de datos de Google Analytics, puedes incluir parámetros de eventos adicionales en el campo additional_event_parameters como una lista de objetos AdditionalEventParameter.
ext	Sin equivalente

Asignación de objetos de datos del usuario

Nota: Consulta la sección Cómo convertir los datos en objetos Event de la guía de envío de eventos para obtener más información sobre los identificadores obligatorios y recomendados para cada destino y caso de uso.

En la API de Data Manager, el campo user_data del objeto Event acepta un objeto UserData. Se espera una lista de objetos UserIdentifier, que pueden contener identificadores de usuarios individuales, como direcciones de correo electrónico, números de teléfono o componentes de direcciones.

ECAPI (user_data)	API de Data Manager (Event)	Notas
customer_identifier	user_id (Google Analytics)	En el caso de los eventos de Google Analytics, el campo user_id representa un User-ID. La API de Data Manager no admite campos de ID de cliente genéricos para otros destinos.
uids	Sin equivalente	La API de Data Manager no admite un array uids estructurado que contenga tipos y dominios de agentes.
customer_segments	user_properties	Mapa a UserProperties en Event.
email_address	user_data.user_identifiers[].email_address	Se establece en la dirección de correo electrónico con formato y hash. También puedes encriptar la dirección de correo electrónico hasheada.
phone_numbers	user_data.user_identifiers[].phone_number	Se establece en el número de teléfono con formato y codificado con hash. También puedes encriptar el número de teléfono codificado con hash.
utcoffset	Sin equivalente	Si usas el formato JSON, puedes especificar el desplazamiento de zona horaria directamente en la cadena event_timestamp de RFC 3339. Si usas búferes de protocolo, puedes usar funciones de utilidad, como Timestamps.parse(String), para controlar la conversión de la zona horaria a segundos y nanosegundos. Consulta Formato de marca de tiempo para obtener más detalles.
address	user_data.user_identifiers[].address	Se asigna a un objeto AddressInfo. Consulta Asignación del objeto Address.
gpp_string	Sin equivalente	El consentimiento debe asignarse al objeto Consent a nivel de la solicitud o del evento. Consulta el Resumen de privacidad y consentimiento.
gpp_sid	Sin equivalente	El consentimiento debe asignarse al objeto Consent a nivel de la solicitud o del evento. Consulta el Resumen de privacidad y consentimiento.
mmt_only	Sin equivalente
click_id	ad_identifiers.gclid	Asigna el ID de clic de Google (gclid). Consulta AdIdentifiers para obtener más detalles.
impression_id	ad_identifiers.impression_id	Consulta AdIdentifiers para obtener más detalles.
event_ip_address	event_device_info.ip_address	Consulta DeviceInfo para ver los campos disponibles.
event_user_agent	event_device_info.user_agent	Consulta DeviceInfo para ver los campos disponibles.
ifa	ad_identifiers.mobile_device_id	Se asigna al identificador de dispositivo móvil para anunciantes (IDFA en iOS y AdID en Android). Consulta AdIdentifiers para obtener más detalles.
landing_ip_address	ad_identifiers.landing_page_device_info.ip_address	Consulta DeviceInfo para ver los campos disponibles.
landing_user_agent	ad_identifiers.landing_page_device_info.user_agent	Consulta DeviceInfo para ver los campos disponibles.
age_range	Sin equivalente
gender	Sin equivalente
ext	Sin equivalente

Asignación de objetos de dirección

ECAPI (address)	API de Data Manager (AddressInfo)	Notas
first_name	given_name	Se asigna al campo given_name en AddressInfo. Sigue los lineamientos de formato y codificación hash. También puedes encriptar los atributos hash de una dirección.
last_name	family_name	Se asigna al campo family_name en AddressInfo. Sigue los lineamientos de formato y codificación hash. También puedes encriptar los atributos hash de una dirección.
street	Sin equivalente	No se admite en la API de Data Manager
city	Sin equivalente	No se admite en la API de Data Manager
state	Sin equivalente	No se admite en la API de Data Manager
country_code	region_code	No generar hash. Se asigna al campo region_code en AddressInfo. Sigue los lineamientos de formato.
postal_code	postal_code	No generar hash. Se asigna al campo postal_code en AddressInfo. Sigue los lineamientos de formato.
address_type	Sin equivalente	No se admite en la API de Data Manager
ext	Sin equivalente

Asignación de objetos de elementos

Sugerencia: Consulta la sección Agrega datos del carrito en la guía de envío de eventos para obtener más información sobre qué campos incluir en los datos del carrito para cada caso de uso de la transferencia de eventos.

ECAPI (item)	API de Data Manager (Item)	Notas
id	item_id	Obligatorio para los eventos de Google Analytics. Se establece en un identificador único estándar para el elemento.
Sin equivalente	merchant_product_id	Obligatorio para las conversiones de Floodlight y las conversiones de Google Ads con datos del carrito. Se establece en el ID del producto dentro de la cuenta de Merchant Center.
name	additional_item_parameters	Mapa como item_name en la lista additional_item_parameters.
price	unit_price
discount	additional_item_parameters o custom_variables	Se asigna como discount en additional_item_parameters (para Google Analytics) o como una variable personalizada en custom_variables (para Google Ads).
quantity	quantity	Convierte el valor float en un número entero (int64).
brand	additional_item_parameters	Mapa como item_brand en la lista additional_item_parameters.
affiliation	additional_item_parameters	Mapa como affiliation en la lista additional_item_parameters.
category	additional_item_parameters	Mapa como item_category en la lista additional_item_parameters.
cattax	Sin equivalente
item_coupon	additional_item_parameters	Mapa como coupon en la lista additional_item_parameters.
item_list_id	additional_item_parameters	Mapa como item_list_id en la lista additional_item_parameters.
item_list_name	additional_item_parameters	Mapa como item_list_name en la lista additional_item_parameters.
item_item_variant	additional_item_parameters	Mapa como item_variant en la lista additional_item_parameters.
item_location_id	additional_item_parameters	Mapa como location_id en additional_item_parameters.
ext	Sin equivalente

Nombres de eventos estándar

Los eventos estándar de la API de EC se alinean en gran medida con las convenciones de nomenclatura de Google Analytics.

• Si envías eventos a un flujo de datos de Google Analytics, el campo event_name es obligatorio.
• Consulta la referencia de eventos recomendados de Google Analytics para conocer los campos, los parámetros y las solicitudes de transferencia de la API de Data Manager de ejemplo asociados a cada evento.
• También puedes enviar eventos personalizados, siempre que cumplan con las reglas para asignar nombres a los eventos.

La mayoría de los eventos estándar de la ECAPI (como purchase, add_to_cart, begin_checkout, search y refund) tienen el mismo nombre que los eventos recomendados de Google Analytics. Sin embargo, hay algunas excepciones en las que Google Analytics usa el tiempo presente en lugar del tiempo pasado:

• viewed_item se asigna a view_item
• viewed_item_list se asigna a view_item_list
• viewed_cart se asigna a view_cart

Solicitudes de ejemplo

En las siguientes pestañas, se muestra una comparación entre una carga útil de eventos de conversión de la ECAPI y su representación como un IngestEventsRequest válido de la API de Data Manager.

ECAPI

A continuación, se incluye una carga útil de JSON de muestra que cumple con la especificación de la 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 de Data Manager

Aquí tienes un ejemplo de IngestEventsRequest para los datos de eventos con formato, codificación hash y codificación. Esto es para un destino de Google Ads, como lo indica el tipo de cuenta GOOGLE_ADS en el 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
          }
        ]
      }
    }
  ]
}