Mapowanie specyfikacji ECAPI

Ten przewodnik pomoże programistom korzystającym ze specyfikacji interfejsu IAB Tech Lab Event and Conversion API (ECAPI) w mapowaniu danych o zdarzeniach i konwersjach na schemat pozyskiwania zdarzeń interfejsu Data Manager API.

Przegląd

ECAPI to niezależny od platformy, otwarty standard danych, który określa strukturę zdarzeń i konwersji związanych z marketingiem.

W tabeli poniżej znajdziesz ogólne porównanie najważniejszych atrybutów i zasad projektowania interfejsu ECAPI z interfejsem Data Manager API.

	ECAPI	Data Manager API
Deduplikacja	Zależy od id (identyfikator zdarzenia)	Zależy od transaction_id
Routing zdarzeń	Miejsce docelowe danych jest wskazywane przez pole data_set_id w ładunku zdarzenia.	Pole destinations w żądaniu określa miejsca docelowe zdarzeń. Interfejs Data Manager API obsługuje też kierowanie zdarzeń do wielu miejsc docelowych w ramach jednego żądania. Więcej informacji znajdziesz w przewodniku po miejscach docelowych.
Pola dotyczące prywatności i zgody użytkownika	Ciągi tekstowe zgody w ramach globalnej platformy do zarządzania prywatnością (GPP)	Interfejs Data Manager API nie akceptuje ani nie analizuje ciągów tekstowych dotyczących zgody użytkowników na globalnej platformie do zarządzania prywatnością (GPP). Pola zgody muszą być ustawione w obiekcie Consent. Możesz ustawić stan zgody na poziomie żądania (co ma zastosowanie do wszystkich zdarzeń w żądaniu) lub na poziomie zdarzenia (co pozwala określić różne ustawienia zgody w przypadku poszczególnych zdarzeń).

Mapowanie pól strukturalnych

W tabelach mapowania poniżej znajdziesz informacje o tym, jak poszczególne pola ze specyfikacji ECAPI są tłumaczone na pola akceptowane przez interfejs Data Manager API.

Wskazówka: aby rozpocząć wysyłanie zdarzeń i dowiedzieć się więcej o polach wymaganych i opcjonalnych w przypadku każdego zastosowania związanego z przetwarzaniem zdarzeń, zapoznaj się z przewodnikiem wysyłania zdarzeń.

Mapowanie obiektów zdarzeń

ECAPI (event)	Interfejs Data Manager API (Event)	Uwagi
data_set_id	destinations[].product_destination_id (na poziomie żądania) destination_references (na poziomie zdarzenia)	Można ją zdefiniować na tych poziomach: Poziom żądania (wymagany): określ listę destinations w IngestEventsRequest. Poziom zdarzenia: użyj pola destination_references w obiekcie Event. Dodaj wpis, aby określić, które miejsce docelowe z listy destinations ma otrzymywać zdarzenie. Więcej informacji o tym, jak zdefiniować Destination i określić identyfikator miejsca docelowego produktu, znajdziesz w artykule Konfigurowanie miejsc docelowych i nagłówków.
id	transaction_id	Ta wartość służy do usuwania duplikatów zdarzeń konwersji. Więcej informacji
timestamp	event_timestamp	Wymagane. W przypadku sygnatur czasowych interfejs ECAPI używa formatu epoki uniksowej (liczba całkowita). Podczas mapowania na interfejs Data Manager API pole event_timestamp musi zostać przekonwertowane na jeden z tych formatów: Jeśli używasz formatu JSON, ustaw wartość w formacie RFC 3339. Jeśli używasz buforów protokołu, użyj Timestamp i ustaw pola seconds oraz (opcjonalnie) nanoseconds. Szczegółowe informacje znajdziesz w sekcji Format sygnatury czasowej.
event_type/custom_event	event_name	Może to być nazwa zalecanego zdarzenia (np. purchase) lub nazwa zdarzenia niestandardowego. Szczegółowe informacje znajdziesz w sekcji Nazwy standardowych zdarzeń.
user_data	user_data	Mapuje na obiekt UserData, który akceptuje listę obiektów UserIdentifier.
value	conversion_value	Mapuj bezpośrednio jako liczbę zmiennoprzecinkową lub zmienną typu double reprezentującą wartość pieniężną konwersji.
currency_code	currency	Mapuj na trzyliterowy kod waluty pisany wielkimi literami (np. USD).
source	event_source	Ustaw na wartość z wyliczenia EventSource.
properties	cart_data custom_variables additional_event_parameters	Elementy na poziomie transakcji można zmapować na tablicę cart_data.items w obiekcie CartData. Interfejs Data Manager API obsługuje kilka opcjonalnych pól Merchant Center dla produktów, które znajdują się na kontach Merchant Center. Jeśli miejscem docelowym jest działanie powodujące konwersję Google Ads, możesz też uwzględnić dodatkowe parametry niestandardowe w polu custom_variables jako listę obiektów CustomVariable. Jeśli miejscem docelowym jest strumień danych Google Analytics, możesz uwzględnić dodatkowe parametry zdarzenia w polu additional_event_parameters jako listę obiektów AdditionalEventParameter.
ext	Brak odpowiednika

Mapowanie obiektów danych użytkownika

Wskazówka: więcej informacji o tym, które identyfikatory są wymagane, a które zalecane w przypadku poszczególnych miejsc docelowych i przypadków użycia, znajdziesz w sekcji Konwertowanie danych na obiekty Event w przewodniku wysyłania zdarzeń.

W interfejsie Data Manager API pole user_data w obiekcie Event akceptuje obiekt UserData. Oczekuje on listy obiektów UserIdentifier, które mogą zawierać poszczególne identyfikatory użytkowników, takie jak adresy e-mail, numery telefonów lub elementy adresu.

ECAPI (user_data)	Interfejs Data Manager API (Event)	Uwagi
customer_identifier	user_id (Google Analytics)	W przypadku zdarzeń Google Analytics pole user_id reprezentuje identyfikator użytkownika. Interfejs Data Manager API nie obsługuje ogólnych pól identyfikatora klienta w przypadku innych miejsc docelowych.
uids	Brak odpowiednika	Interfejs Data Manager API nie obsługuje uporządkowanej tablicy uids zawierającej typy agentów i domeny.
customer_segments	user_properties	Mapa do UserProperties na Event.
email_address	user_data.user_identifiers[].email_address	Ustaw na sformatowany i zaszyfrowany adres e-mail. Możesz też zaszyfrować zaszyfrowany adres e-mail.
phone_numbers	user_data.user_identifiers[].phone_number	Ustaw na sformatowany i zahaszowany numer telefonu. Możesz też zaszyfrować zahaszowany numer telefonu.
utcoffset	Brak odpowiednika	Jeśli używasz formatu JSON, możesz określić przesunięcie strefy czasowej bezpośrednio w ciągu RFC 3339 event_timestamp. Jeśli używasz buforów protokołu, możesz użyć funkcji narzędziowych, takich jak Timestamps.parse(String), do obsługi konwersji strefy czasowej na sekundy i nanosekundy. Szczegółowe informacje znajdziesz w sekcji Format sygnatury czasowej.
address	user_data.user_identifiers[].address	Mapuje się na obiekt AddressInfo. Zobacz Mapowanie obiektu Address.
gpp_string	Brak odpowiednika	Zgoda musi być przypisana do obiektu Consent na poziomie żądania lub zdarzenia. Zapoznaj się z omówieniem prywatności i zgody.
gpp_sid	Brak odpowiednika	Zgoda musi być przypisana do obiektu Consent na poziomie żądania lub zdarzenia. Zapoznaj się z omówieniem prywatności i zgody.
mmt_only	Brak odpowiednika
click_id	ad_identifiers.gclid	Mapuj na identyfikator kliknięcia Google (gclid). Więcej informacji znajdziesz w AdIdentifiers.
impression_id	ad_identifiers.impression_id	Więcej informacji znajdziesz w sekcji AdIdentifiers.
event_ip_address	event_device_info.ip_address	Dostępne pola znajdziesz w sekcji DeviceInfo.
event_user_agent	event_device_info.user_agent	Dostępne pola znajdziesz w sekcji DeviceInfo.
ifa	ad_identifiers.mobile_device_id	Mapowanie na identyfikator wyświetlania reklam mobilnych dla reklamodawców (IDFA w iOS, AdID w Androidzie). Więcej informacji znajdziesz w sekcji AdIdentifiers.
landing_ip_address	ad_identifiers.landing_page_device_info.ip_address	Dostępne pola znajdziesz w sekcji DeviceInfo.
landing_user_agent	ad_identifiers.landing_page_device_info.user_agent	Dostępne pola znajdziesz w sekcji DeviceInfo.
age_range	Brak odpowiednika
gender	Brak odpowiednika
ext	Brak odpowiednika

Mapowanie obiektu Address

ECAPI (address)	Interfejs Data Manager API (AddressInfo)	Uwagi
first_name	given_name	Mapuje się na pole given_name w AddressInfo. Postępuj zgodnie z wytycznymi dotyczącymi formatowania i haszowania. Możesz też zaszyfrować zahaszowane atrybuty adresu.
last_name	family_name	Mapuje się na pole family_name w AddressInfo. Postępuj zgodnie z wytycznymi dotyczącymi formatowania i haszowania. Możesz też zaszyfrować zahaszowane atrybuty adresu.
street	Brak odpowiednika	Nieobsługiwane w interfejsie Data Manager API
city	Brak odpowiednika	Nieobsługiwane w interfejsie Data Manager API
state	Brak odpowiednika	Nieobsługiwane w interfejsie Data Manager API
country_code	region_code	Nie używaj haszowania. Odpowiada polu region_code w AddressInfo. Postępuj zgodnie z wytycznymi dotyczącymi formatowania.
postal_code	postal_code	Nie używaj haszowania. Odpowiada polu postal_code w AddressInfo. Postępuj zgodnie z wytycznymi dotyczącymi formatowania.
address_type	Brak odpowiednika	Nieobsługiwane w interfejsie Data Manager API
ext	Brak odpowiednika

Mapowanie obiektów produktów

Wskazówka: więcej informacji o tym, które pola należy uwzględnić w danych koszyka w przypadku każdego zastosowania związanego z przetwarzaniem zdarzeń, znajdziesz w sekcji Dodawanie danych koszyka w przewodniku wysyłania zdarzeń.

ECAPI (item)	Interfejs Data Manager API (Item)	Uwagi
id	item_id	Wymagany w przypadku zdarzeń Google Analytics. Ustaw na standardowy, unikalny identyfikator produktu.
Brak odpowiednika	merchant_product_id	Wymagany w przypadku konwersji Floodlight i konwersji Google Ads z danymi koszyka. Ustawiony na identyfikator produktu na koncie Merchant Center.
name	additional_item_parameters	Mapa jako item_name na liście additional_item_parameters.
price	unit_price
discount	additional_item_parameters lub custom_variables	Mapuj jako discount w additional_item_parameters (w przypadku Google Analytics) lub jako zmienną niestandardową w custom_variables (w przypadku Google Ads).
quantity	quantity	Przekształć wartość float w liczbę całkowitą (int64).
brand	additional_item_parameters	Mapa jako item_brand na liście additional_item_parameters.
affiliation	additional_item_parameters	Mapa jako affiliation na liście additional_item_parameters.
category	additional_item_parameters	Mapa jako item_category na liście additional_item_parameters.
cattax	Brak odpowiednika
item_coupon	additional_item_parameters	Mapa jako coupon na liście additional_item_parameters.
item_list_id	additional_item_parameters	Mapa jako item_list_id na liście additional_item_parameters.
item_list_name	additional_item_parameters	Mapa jako item_list_name na liście additional_item_parameters.
item_item_variant	additional_item_parameters	Mapa jako item_variant na liście additional_item_parameters.
item_location_id	additional_item_parameters	Mapa: location_id w: additional_item_parameters.
ext	Brak odpowiednika

Nazwy zdarzeń standardowych

Standardowe zdarzenia ECAPI są w dużej mierze zgodne z konwencjami nazewnictwa Google Analytics.

• Jeśli wysyłasz zdarzenia do strumienia danych Google Analytics, pole event_name jest wymagane.
• Zapoznaj się z dokumentacją zalecanych zdarzeń w Google Analytics, aby poznać powiązane pola, parametry i przykładowe żądania przesyłania danych do interfejsu Data Manager API dla każdego zdarzenia.
• Możesz też wysyłać zdarzenia niestandardowe, o ile są zgodne z regułami nadawania nazw zdarzeniom.

Większość standardowych zdarzeń ECAPI (np. purchase,add_to_cart, begin_checkout, search i refund) ma taką samą nazwę jak zalecane zdarzenia Google Analytics. Istnieje jednak kilka wyjątków, w których Google Analytics używa czasu teraźniejszego zamiast przeszłego:

• viewed_item map do view_item
• viewed_item_list map do view_item_list
• viewed_cart map do view_cart

Przykładowe żądania

Na kartach poniżej znajdziesz porównanie ładunku zdarzenia konwersji ECAPI i jego reprezentacji jako prawidłowego interfejsu Data Manager APIIngestEventsRequest.

ECAPI

Oto przykładowy ładunek JSON zgodny ze specyfikacją 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
      }
    ]
  }
}

Data Manager API

Oto przykładowy ciąg IngestEventsRequest sformatowanych, zaszyfrowanych i zakodowanych danych zdarzenia. Dotyczy to miejsca docelowego Google Ads, co wskazuje typ konta GOOGLE_ADS w miejscu docelowym.

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