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) de 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 que define la estructura de 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 ECAPI con la API de Data Manager:

ECAPI API de Data Manager
Anulación de duplicación Se basa en id (ID del evento) Se requiere 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 múltiples destinos en una sola solicitud.

Consulta Configura destinos y encabezados 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 Global Privacy Platform (GPP). Configura los campos de consentimiento 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 de 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 en campos que acepta la API de Data Manager:

Asignación de objetos de evento

ECAPI (event) API de Data Manager (Event) Notas
data_set_id
  • destinations[].product_destination_id (nivel de solicitud)
  • destination_references (a nivel del evento)
 Puedes definir destinos en los siguientes niveles:
  • Nivel de solicitud (obligatorio): Especifica la lista de destinations en el IngestEventsRequest.
  • A nivel del evento (opcional): Usa el campo destination_references en el 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 de destino del producto, consulta Configura destinos y encabezados.
id transaction_id Anula los eventos de conversión duplicados. Consulta Cómo Google procesa los datos de múltiples fuentes en las guías de Envío de eventos para Google Ads, Google Analytics y Floodlight.
timestamp event_timestamp Obligatorio. La ECAPI usa el formato de tiempo Unix (número entero) para las marcas de tiempo. Cuando realices la asignación a la API de Data Manager, convierte el campo event_timestamp en uno de los siguientes formatos:
  • Si usas el formato JSON, establece un valor en el formato RFC 3339.
  • Si usas búferes de protocolo, usa un Timestamp y configura los campos seconds y nanoseconds (opcional).

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 Asigna un mapa a un código de moneda de tres letras en mayúsculas (por ejemplo, USD).
source event_source Se establece en un valor de la enumeración EventSource.
properties
  • cart_data
  • custom_variables
  • additional_event_parameters
 Asigna los elementos a nivel de la transacción al array cart_data.items en el objeto CartData. La API de Data Manager admite varios campos de Merchant Center opcionales 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 No hay equivalente

Asignación de objetos de datos del usuario

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 No hay equivalente La API de Data Manager no admite un array uids estructurado que contenga tipos de agentes y dominios.
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 con codificación hash.
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 con codificación hash.
utcoffset No hay equivalente Si usas el formato JSON, puedes especificar la diferencia 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 de objetos de dirección.
gpp_string No hay equivalente Asigna el consentimiento al objeto Consent a nivel de la solicitud o del evento. Consulta la descripción general de Privacidad y consentimiento.
gpp_sid Sin equivalente Asigna el consentimiento al objeto Consent a nivel de la solicitud o del evento. Consulta la Descripción general de la privacidad y el consentimiento.
mmt_only No hay 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 información.
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 Asigna el identificador de dispositivo móvil para anunciantes (IDFA en iOS, AdID en Android). Consulta AdIdentifiers para obtener más información.
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 No hay 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 con codificación 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 con codificación 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 uses un hash. Se asigna al campo region_code en AddressInfo. Sigue los lineamientos de formato.
postal_code postal_code No uses un hash. Se asigna al campo postal_code en AddressInfo. Sigue los lineamientos de formato.
address_type No hay equivalente No se admite en la API de Data Manager.
ext Sin equivalente

Asignación de objetos de elementos

ECAPI (item) API de Data Manager (Item) Notas
id item_id Obligatorio para los eventos de Google Analytics. Establece un identificador único estándar para el artículo.
No hay 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 Asigna el parámetro 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 Asigna 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 Asigna como item_category en la lista additional_item_parameters.
cattax No hay 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 Asigna como item_variant en la lista additional_item_parameters.
item_location_id additional_item_parameters Mapa como location_id en additional_item_parameters.
ext No hay equivalente

Nombres de eventos estándar

Los eventos estándar de la ECAPI se alinean en gran medida con las convenciones de nombres de Google Analytics.

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 de evento que los eventos recomendados de Google Analytics. Sin embargo, existen algunas excepciones en las que Google Analytics usa el tiempo presente en lugar del 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 un evento de conversión de la ECAPI y su representación como un IngestEventsRequest válido de la API de Data Manager:

ECAPI

Esta es una carga útil de muestra en formato JSON 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

Este es un ejemplo de IngestEventsRequest para los datos del evento con formato, codificación hash y codificación. El tipo de cuenta GOOGLE_ADS en el destino indica que la solicitud se dirige a un destino de 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
          }
        ]
      }
    }
  ]
}