Mappatura delle specifiche ECAPI

Questa guida aiuta gli sviluppatori che utilizzano la specifica dell'API Event and Conversion (ECAPI) di IAB Tech Lab a mappare i dati sugli eventi e sulle conversioni allo schema di importazione degli eventi dell'API Data Manager.

Panoramica

L'API EC è uno standard di dati open source indipendente dalla piattaforma che definisce la struttura di eventi e conversioni correlati al marketing.

La tabella seguente fornisce una panoramica di alto livello del confronto tra gli attributi chiave e i principi di progettazione di ECAPI e l'API Data Manager:

ECAPI API Data Manager
Deduplicazione Si basa su id (ID evento) Si basa su transaction_id
Routing degli eventi Il campo data_set_id nel payload dell'evento indica la destinazione dei dati. Il campo destinations della richiesta definisce le destinazioni degli eventi.

L'API Data Manager supporta anche il routing degli eventi a più destinazioni in un'unica richiesta.

Per saperne di più, consulta Configurare destinazioni e intestazioni.
Campi relativi alla privacy e al consenso Stringhe di consenso della Global Privacy Platform (GPP) L'API Data Manager non accetta né analizza le stringhe di consenso della Global Privacy Platform (GPP). Imposta i campi relativi al consenso nell'oggetto Consent.

Puoi impostare il consenso a livello di richiesta (che si applica a tutti gli eventi della richiesta) o a livello di evento (che ti consente di specificare impostazioni di consenso diverse per i singoli eventi).

Mappatura dei campi strutturali

Le seguenti tabelle di mappatura definiscono il modo in cui i singoli campi della specifica ECAPI vengono tradotti in campi accettati dall'API Data Manager:

Mappatura degli oggetti evento

ECAPI (event) API Data Manager (Event) Note
data_set_id
  • destinations[].product_destination_id (Livello di richiesta)
  • destination_references (a livello di evento)
 Puoi definire le destinazioni ai seguenti livelli:
  • Livello di richiesta (obbligatorio): specifica l'elenco di destinations in IngestEventsRequest.
  • Livello di evento (facoltativo): utilizza il campo destination_references nell'oggetto Event. Aggiungi una voce per specificare quale destinazione dell'elenco destinations deve ricevere l'evento.

Per saperne di più su come definire un Destination e determinare l'ID destinazione prodotto, consulta Configura destinazioni e intestazioni.
id transaction_id Deduplica gli eventi di conversione. Consulta la sezione Come Google gestisce i dati multiorigine nelle guide Invia eventi per Google Ads, Google Analytics e Floodlight.
timestamp event_timestamp Obbligatorio. L'API per le conversioni avanzate utilizza il formato dell'epoca di Unix (numero intero) per i timestamp. Quando esegui la mappatura all'API Data Manager, converti il campo event_timestamp in uno dei seguenti formati:
  • Se utilizzi il formato JSON, imposta un valore nel formato RFC 3339.
  • Se utilizzi buffer di protocollo, usa un Timestamp e imposta i campi seconds e (facoltativamente) nanoseconds.

Per maggiori dettagli, consulta Formato del timestamp.
event_type/custom_event event_name Può trattarsi di un nome evento consigliato (ad esempio purchase) o di un nome evento personalizzato. Per maggiori dettagli, vedi Nomi degli eventi standard.
user_data user_data Esegue la mappatura all'oggetto UserData, che accetta un elenco di oggetti UserIdentifier.
value conversion_value Esegui la mappatura direttamente come un valore double o float che rappresenta il valore monetario della conversione.
currency_code currency Mappa a un codice valuta di tre lettere maiuscole (ad esempio, USD).
source event_source Imposta un valore dall'enum EventSource.
properties
  • cart_data
  • custom_variables
  • additional_event_parameters
 Mappa gli elementi a livello di transazione all'array cart_data.items nell'oggetto CartData. L'API Data Manager supporta diversi campi di Merchant Center facoltativi per i prodotti esistenti negli account Merchant Center.

Se la destinazione è un'azione di conversione Google Ads, puoi includere anche parametri personalizzati aggiuntivi nel campo custom_variables come elenco di oggetti CustomVariable.

Se la destinazione è uno stream di dati di Google Analytics, puoi includere parametri evento aggiuntivi nel campo additional_event_parameters come elenco di oggetti AdditionalEventParameter.
ext Nessun equivalente

Mappatura degli oggetti dati utente

Nell'API Data Manager, il campo user_data dell'oggetto Event accetta un oggetto UserData. Questo campo prevede un elenco di oggetti UserIdentifier, che possono contenere identificatori dell'utente individuali come indirizzi email, numeri di telefono o componenti di indirizzi:

ECAPI (user_data) API Data Manager (Event) Note
customer_identifier user_id (Google Analytics) Per gli eventi di Google Analytics, il campo user_id rappresenta uno User-ID. L'API Data Manager non supporta i campi ID cliente generici per altre destinazioni.
uids Nessun equivalente L'API Data Manager non supporta un array uids strutturato contenente tipi di agenti e domini.
customer_segments user_properties Mappa a UserProperties su Event.
email_address user_data.user_identifiers[].email_address Imposta l'indirizzo email formattato e sottoposto ad hashing. Puoi anche criptare l'indirizzo email sottoposto ad hashing.
phone_numbers user_data.user_identifiers[].phone_number Imposta il numero di telefono formattato e sottoposto ad hashing. Puoi anche criptare il numero di telefono sottoposto ad hashing.
utcoffset Nessun equivalente Se utilizzi il formato JSON, puoi specificare l'offset del fuso orario direttamente nella stringa RFC 3339 event_timestamp.
Se utilizzi i buffer di protocollo, puoi utilizzare funzioni di utilità come Timestamps.parse(String) per gestire la conversione del fuso orario in secondi e nanosecondi.
Per maggiori dettagli, consulta la sezione Formato per il timestamp.
address user_data.user_identifiers[].address Mappa a un oggetto AddressInfo. Consulta Mappatura degli oggetti Address.
gpp_string Nessun equivalente Mappa il consenso all'oggetto Consent a livello di richiesta o di evento. Consulta la panoramica su privacy e consenso.
gpp_sid Nessun equivalente Mappa il consenso all'oggetto Consent a livello di richiesta o di evento. Consulta la panoramica su privacy e consenso.
mmt_only Nessun equivalente
click_id ad_identifiers.gclid Mappa all'ID clic Google (gclid). Per ulteriori dettagli, consulta AdIdentifiers.
impression_id ad_identifiers.impression_id Per maggiori dettagli, consulta AdIdentifiers.
event_ip_address event_device_info.ip_address Consulta DeviceInfo per i campi disponibili.
event_user_agent event_device_info.user_agent Consulta DeviceInfo per i campi disponibili.
ifa ad_identifiers.mobile_device_id Esegui la mappatura all'identificatore mobile per gli inserzionisti (IDFA su iOS, AdID su Android). Per maggiori dettagli, consulta AdIdentifiers.
landing_ip_address ad_identifiers.landing_page_device_info.ip_address Consulta DeviceInfo per i campi disponibili.
landing_user_agent ad_identifiers.landing_page_device_info.user_agent Consulta DeviceInfo per i campi disponibili.
age_range Nessun equivalente
gender Nessun equivalente
ext Nessun equivalente

Mappatura degli oggetti Address

ECAPI (address) API Data Manager (AddressInfo) Note
first_name given_name Mappa al campo given_name in AddressInfo. Segui le linee guida sulla formattazione e sull'hashing. Puoi anche criptare gli attributi con hash di un indirizzo.
last_name family_name Corrisponde al campo family_name in AddressInfo. Segui le linee guida sulla formattazione e sull'hashing. Puoi anche criptare gli attributi con hash di un indirizzo.
street Nessun equivalente Non supportato nell'API Data Manager.
city Nessun equivalente Non supportato nell'API Data Manager.
state Nessun equivalente Non supportato nell'API Data Manager.
country_code region_code Non sottoporre ad hashing. Corrisponde al campo region_code in AddressInfo. Segui le linee guida per la formattazione.
postal_code postal_code Non sottoporre ad hashing. Corrisponde al campo postal_code in AddressInfo. Segui le linee guida per la formattazione.
address_type Nessun equivalente Non supportato nell'API Data Manager.
ext Nessun equivalente

Mappatura degli oggetti elemento

ECAPI (item) API Data Manager (Item) Note
id item_id Obbligatorio per gli eventi di Google Analytics. Impostato su un identificatore univoco standard per l'elemento.
Nessun equivalente merchant_product_id Obbligatorio per le conversioni Floodlight e le conversioni di Google Ads con dati del carrello. Impostato sull'ID prodotto all'interno dell'account Merchant Center.
name additional_item_parameters Mappa come item_name nell'elenco additional_item_parameters.
price unit_price
discount additional_item_parameters o custom_variables Esegui la mappatura come discount in additional_item_parameters (per Google Analytics) o come variabile personalizzata in custom_variables (per Google Ads).
quantity quantity Converti il valore float in un numero intero (int64).
brand additional_item_parameters Mappa come item_brand nell'elenco additional_item_parameters.
affiliation additional_item_parameters Mappa come affiliation nell'elenco additional_item_parameters.
category additional_item_parameters Mappa come item_category nell'elenco additional_item_parameters.
cattax Nessun equivalente
item_coupon additional_item_parameters Mappa come coupon nell'elenco additional_item_parameters.
item_list_id additional_item_parameters Mappa come item_list_id nell'elenco additional_item_parameters.
item_list_name additional_item_parameters Mappa come item_list_name nell'elenco additional_item_parameters.
item_item_variant additional_item_parameters Mappa come item_variant nell'elenco additional_item_parameters.
item_location_id additional_item_parameters Mappa come location_id in additional_item_parameters.
ext Nessun equivalente

Nomi degli eventi standard

Gli eventi standard dell'API Conversioni avanzate sono strettamente allineati alle convenzioni di denominazione di Google Analytics.

La maggior parte degli eventi standard dell'API EC (come purchase, add_to_cart, begin_checkout, search e refund) ha lo stesso nome evento degli eventi consigliati di Google Analytics. Tuttavia, esistono alcune eccezioni in cui Google Analytics utilizza il tempo presente anziché il passato:

  • viewed_item corrisponde a view_item

  • Mappe di viewed_item_list a view_item_list

  • Mappe di viewed_cart a view_cart

Esempi di richieste

Le seguenti schede mostrano un confronto tra un payload di eventi di conversione ECAPI e la sua rappresentazione come IngestEventsRequest dell'API Data Manager valido:

ECAPI

Ecco un payload JSON di esempio conforme alla specifica 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

Ecco un esempio di IngestEventsRequest per i dati sugli eventi formattati, sottoposti ad hashing e codificati. Il tipo di account GOOGLE_ADS nella destinazione indica che la richiesta ha come target una destinazione 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
          }
        ]
      }
    }
  ]
}