Mapowanie specyfikacji ECAPI

Ten przewodnik pomoże deweloperom korzystającym ze specyfikacji interfejsu IAB Tech Lab Event and Conversion API (ECAPI) zmapować dane o zdarzeniach i konwersjach na schemat wprowadzania zdarzeń interfejsu Data Manager API.

Przegląd

ECAPI to niezależny od platformy standard danych typu open source, który definiuje 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
Kierowanie zdarzeń Pole data_set_id w ładunku zdarzenia wskazuje miejsce docelowe danych. Pole destinations żądania 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 artykule Konfigurowanie miejsc docelowych i nagłówków.
Pola dotyczące prywatności i zgody użytkownika Ciągi tekstowe dotyczące zgody na globalnej platformie do zarządzania prywatnością (GPP) Interfejs Data Manager API nie akceptuje ani nie analizuje ciągów tekstowych dotyczących zgody użytkownika z globalnej platformy do zarządzania prywatnością (GPP). Ustaw pola zgody 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ą przekształcane w pola akceptowane przez interfejs Data Manager API:

Mapowanie obiektów zdarzeń

ECAPI (event) Interfejs Data Manager API (Event) Uwagi
data_set_id
  • destinations[].product_destination_id (poziom żądania)
  • destination_references (na poziomie zdarzenia)
 Miejsca docelowe możesz definiować na tych poziomach:
  • Poziom żądania (wymagany): określ listę destinations w IngestEventsRequest.
  • Poziom zdarzenia (opcjonalnie): 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 definiowaniu Destination i określaniu identyfikatora miejsca docelowego usługi znajdziesz w artykule Konfigurowanie miejsc docelowych i nagłówków.
id transaction_id Usuwa duplikaty zdarzeń konwersji. W przewodnikach Wysyłanie zdarzeń dotyczących Google Ads, Google Analytics i Floodlight znajdziesz informacje o tym, jak Google postępuje z danymi z wielu źródeł.
timestamp event_timestamp Parametr wymagany. W przypadku sygnatur czasowych interfejs ECAPI używa formatu epoki uniksowej (liczba całkowita). Podczas mapowania na interfejs Data Manager API przekonwertuj pole event_timestamp 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. Więcej informacji znajdziesz w artykule Standardowe nazwy 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ą podwójnej precyzji lub pojedynczej precyzji reprezentującą wartość pieniężną konwersji.
currency_code currency Mapuj na trzyliterowy kod waluty pisany wielkimi literami (np. USD).
source event_source Ustaw wartość z wyliczenia EventSource.
properties
  • cart_data
  • custom_variables
  • additional_event_parameters
 Zmapuj elementy na poziomie transakcji na tablicę cart_data.items w obiekcie CartData. Interfejs Data Manager API obsługuje kilka opcjonalnych pól Merchant Center dotyczących produktów, które znajdują się na kontach Merchant Center.

Jeśli miejscem docelowym jest działanie powodujące konwersję z reklam 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

W interfejsie Data Manager API pole user_data w obiekcie Event akceptuje obiekt UserData. Wymaga to 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 User-ID. 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 strukturalnej tablicy uids zawierającej typy agentów i domeny.
customer_segments user_properties Mapuj na UserProperties w Event.
email_address user_data.user_identifiers[].email_address Ustaw sformatowany i zaszyfrowany adres e-mail. Możesz też zaszyfrować zaszyfrowany adres e-mail.
phone_numbers user_data.user_identifiers[].phone_number Ustaw 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 na obiekt AddressInfo. Zobacz mapowanie obiektu Address.
gpp_string Brak odpowiednika Mapowanie zgody na obiekt Consent na poziomie żądania lub zdarzenia. Zobacz Prywatność i zgoda użytkowników – omówienie.
gpp_sid Brak odpowiednika Mapowanie zgody na obiekt 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 artykule AdIdentifiers.
impression_id ad_identifiers.impression_id Więcej informacji znajdziesz na stronie AdIdentifiers.
event_ip_address event_device_info.ip_address Dostępne pola znajdziesz w DeviceInfo.
event_user_agent event_device_info.user_agent Dostępne pola znajdziesz w DeviceInfo.
ifa ad_identifiers.mobile_device_id Mapuj na identyfikator wyświetlania reklam mobilnych (IDFA na iOS, AdID na Androidzie). Więcej informacji znajdziesz na stronie 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 obiektów adresów

ECAPI (address) Interfejs Data Manager API (AddressInfo) Uwagi
first_name given_name Mapuje na pole given_name w AddressInfo. Postępuj zgodnie z wytycznymi dotyczącymi formatowania i szyfrowania. Możesz też zaszyfrować zaszyfrowane atrybuty adresu.
last_name family_name Mapuje na pole family_name w AddressInfo. Postępuj zgodnie z wytycznymi dotyczącymi formatowania i szyfrowania. Możesz też zaszyfrować zaszyfrowane atrybuty adresu.
street Brak odpowiednika Nie jest obsługiwany w interfejsie Data Manager API.
city Brak odpowiednika Nie jest obsługiwany w interfejsie Data Manager API.
state Brak odpowiednika Nie jest obsługiwany w interfejsie Data Manager API.
country_code region_code Nie szyfruj. Mapuje na pole region_code w AddressInfo. Postępuj zgodnie z wytycznymi dotyczącymi formatowania.
postal_code postal_code Nie szyfruj. Mapuje na pole postal_code w AddressInfo. Postępuj zgodnie z wytycznymi dotyczącymi formatowania.
address_type Brak odpowiednika Nie jest obsługiwany w interfejsie Data Manager API.
ext Brak odpowiednika

Mapowanie obiektów elementów

ECAPI (item) Interfejs Data Manager API (Item) Uwagi
id item_id Wymagane w przypadku zdarzeń Google Analytics. Ustaw standardowy, unikalny identyfikator elementu.
Brak odpowiednika merchant_product_id Wymagane w przypadku konwersji Floodlight i konwersji Google Ads z danymi koszyka. Ustaw identyfikator produktu na koncie Merchant Center.
name additional_item_parameters Mapuj 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 Przekonwertuj wartość float na 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 Mapuj jako coupon na liście additional_item_parameters.
item_list_id additional_item_parameters Mapuj jako item_list_id na liście additional_item_parameters.
item_list_name additional_item_parameters Mapuj jako item_list_name na liście additional_item_parameters.
item_item_variant additional_item_parameters Mapuj 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.

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 mapuje na view_item

  • viewed_item_list mapuje na view_item_list

  • viewed_cart odpowiada view_cart

Przykładowe żądania

Na kartach poniżej znajdziesz porównanie ładunku zdarzenia konwersji ECAPI z jego reprezentacją jako prawidłowego obiektu IngestEventsRequest interfejsu Data Manager API:

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 IngestEventsRequest sformatowanych, zaszyfrowanych i zakodowanych danych zdarzenia. Typ konta GOOGLE_ADS w miejscu docelowym wskazuje, że żądanie jest kierowane do miejsca docelowego 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
          }
        ]
      }
    }
  ]
}