Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Mappatura delle specifiche ECAPI

Questa guida aiuta gli sviluppatori che utilizzano la specifica dell'API Eventi e conversioni (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 progettato per definire 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 dell'API ECAPI e dell'API Data Manager.

	ECAPI	API Data Manager
Deduplicazione	Si basa su `id` (ID evento)	Si basa su `transaction_id`
Routing eventi	La destinazione dei dati è indicata dal campo `data_set_id` nel payload dell'evento.	Il campo `destinations` della richiesta definisce le destinazioni degli eventi. L'API Data Manager supporta anche l'instradamento degli eventi a più destinazioni in un'unica richiesta. Per saperne di più, consulta la guida alle destinazioni.
Campi relativi a privacy e 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). I campi relativi al consenso devono essere impostati nell'oggetto `Consent`. Puoi impostare il consenso a livello di richiesta (che si applica a tutti gli eventi nella richiesta) o a livello di evento (che ti consente di specificare impostazioni di consenso diverse per i singoli eventi).

Mappatura dei campi strutturati

Le seguenti tabelle di mappatura definiscono come i singoli campi della specifica ECAPI vengono tradotti in campi accettati dall'API Data Manager.

Mappatura dell'oggetto evento

ECAPI (`event`)	API Data Manager (`Event`)	Note
`data_set_id`	`destinations[].product_destination_id` (livello di richiesta) `destination_references` (a livello di evento)	Può essere definito ai seguenti livelli: Livello di richiesta (obbligatorio): specifica l'elenco di `destinations` in `IngestEventsRequest`. Livello di evento: utilizza il campo `destination_references` nell'oggetto `Event`. Aggiungi una voce per specificare quale destinazione dell'elenco `destinations` deve ricevere l'evento. Per ulteriori informazioni su come definire un `Destination` e determinare l'ID destinazione prodotto, consulta Configurare destinazioni e intestazioni.
`id`	`transaction_id`	Questo valore viene utilizzato per deduplicare gli eventi di conversione. Ulteriori informazioni.
`timestamp`	`event_timestamp`	Obbligatorio. L'API per le conversioni avanzate utilizza il formato Unix epoch (numero intero) per i timestamp. Quando esegui il mapping all'API Data Manager, il campo `event_timestamp` deve essere convertito in uno dei seguenti formati: Se utilizzi il formato JSON, imposta un valore nel formato RFC 3339. Se utilizzi i buffer di protocollo, usa un `Timestamp` e imposta i campi `seconds` e (facoltativamente) `nanoseconds`. Per maggiori dettagli, vedi Formato per il 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`	Mappa all'oggetto `UserData`, che accetta un elenco di oggetti `UserIdentifier`.
`value`	`conversion_value`	Mappa 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`	Impostato su un valore dell'enumerazione EventSource.
`properties`	`cart_data` `custom_variables` `additional_event_parameters`	Gli elementi a livello di transazione possono essere mappati 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 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 prevede un elenco di oggetti UserIdentifier, che possono contenere identificatori 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 Google Analytics, il campo `user_id` rappresenta un 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 per `UserProperties` su `Event`.
`email_address`	`user_data.user_identifiers[].email_address`	Impostato sull'indirizzo email formattato e sottoposto ad hashing. Puoi anche criptare l'indirizzo email sottoposto ad hashing.
`phone_numbers`	`user_data.user_identifiers[].phone_number`	Impostato sul 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 `event_timestamp` RFC 3339. 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, vedi Formato per il timestamp.
`address`	`user_data.user_identifiers[].address`	Mappa a un oggetto `AddressInfo`. Vedi Mappatura dell'oggetto Address.
`gpp_string`	Nessun equivalente	Il consenso deve essere mappato all'oggetto `Consent` a livello di richiesta o evento. Consulta la Panoramica su privacy e consenso.
`gpp_sid`	Nessun equivalente	Il consenso deve essere mappato all'oggetto `Consent` a livello di richiesta o evento. Consulta la Panoramica su privacy e consenso.
`mmt_only`	Nessun equivalente
`click_id`	`ad_identifiers.gclid`	Mappa all'ID clic Google (`gclid`). Per maggiori dettagli, consulta `AdIdentifiers`.
`impression_id`	`ad_identifiers.impression_id`	Per ulteriori 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`	Mappa l'identificatore mobile per gli inserzionisti (IDFA su iOS, ID pubblicità su Android). Per ulteriori 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

Mapping dell'oggetto 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 sottoposti ad hashing di un indirizzo.
`last_name`	`family_name`	Mappa al campo `family_name` in `AddressInfo`. Segui le linee guida sulla formattazione e sull'hashing. Puoi anche criptare gli attributi sottoposti ad hashing 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 utilizzare l'hash. Corrisponde al campo `region_code` in `AddressInfo`. Segui le linee guida per la formattazione.
`postal_code`	`postal_code`	Non utilizzare l'hash. 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 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`	Mappa 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 di `location_id` in `additional_item_parameters`.
`ext`	Nessun equivalente

Nomi degli eventi standard

Gli eventi standard ECAPI sono in gran parte in linea con le convenzioni di denominazione di Google Analytics.

Se invii eventi a uno stream di dati Google Analytics, il campo event_name è obbligatorio.
Consulta il riferimento agli eventi consigliati di Google Analytics per campi, parametri e richieste di importazione dell'API Data Manager di esempio per ogni evento.
Puoi anche inviare eventi personalizzati, a condizione che rispettino le regole di denominazione degli eventi.

La maggior parte degli eventi standard ECAPI (ad esempio 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
viewed_item_list corrisponde a view_item_list
viewed_cart corrisponde a view_cart

Esempi di richieste

Le seguenti schede mostrano un confronto tra un payload di un evento di conversione dell'API Conversions e la sua rappresentazione come IngestEventsRequest valido dell'API Data Manager.

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. Si tratta di una destinazione Google Ads, come indicato dal tipo di account GOOGLE_ADS nella destinazione.

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