ECAPI-Spezifikationszuordnung

In dieser Anleitung erfahren Entwickler, die die IAB Tech Lab Event and Conversion API (ECAPI)-Spezifikation verwenden, wie sie ihre Ereignis- und Conversion-Daten dem Schema für die Ereignisaufnahme der Data Manager API zuordnen.

Übersicht

ECAPI ist ein plattformunabhängiger Open-Source-Datenstandard, der definiert, wie marketingbezogene Ereignisse und Conversions strukturiert werden.

In der folgenden Tabelle sehen Sie einen allgemeinen Vergleich der wichtigsten Attribute und Designprinzipien von ECAPI und Data Manager API.

	ECAPI	Data Manager API
Deduplizierung	Basiert auf id (Ereignis-ID)	Basiert auf transaction_id
Ereignisrouting	Das Ziel der Daten wird durch das Feld data_set_id in der Ereignisnutzlast angegeben.	Im Feld destinations der Anfrage werden die Ziele für die Ereignisse definiert. Die Data Manager API unterstützt auch das Weiterleiten von Ereignissen an mehrere Ziele in einer einzigen Anfrage. Weitere Informationen finden Sie im Leitfaden zu Zielen.
Datenschutz- und Einwilligungsfelder	Einwilligungsstrings der Global Privacy Platform (GPP)	Die Data Manager API akzeptiert oder parst keine Consent-Strings der Global Privacy Platform (GPP). Die Einwilligungsfelder müssen im Objekt Consent festgelegt werden. Sie können die Einwilligung entweder auf Anfrageebene (gilt für alle Ereignisse in der Anfrage) oder auf Ereignisebene festlegen (damit lassen sich verschiedene Einwilligungseinstellungen für einzelne Ereignisse angeben).

Strukturelle Feldzuordnung

In den folgenden Zuordnungstabellen wird definiert, wie einzelne Felder aus der ECAPI-Spezifikation in Felder übersetzt werden, die von der Data Manager API akzeptiert werden.

Tipp :Im Leitfaden zum Senden von Ereignissen finden Sie Informationen zum Senden von Ereignissen und zu den erforderlichen und optionalen Feldern für die einzelnen Anwendungsfälle für die Ereignisaufnahme.

Zuordnung von Ereignisobjekten

ECAPI (event)	Data Manager API (Event)	Hinweise
data_set_id	destinations[].product_destination_id (Anfrageebene) destination_references (Ereignisebene)	Kann auf den folgenden Ebenen definiert werden: Anfrageebene (erforderlich): Geben Sie die Liste der destinations im IngestEventsRequest an. Ereignisebene: Verwenden Sie das Feld destination_references im Objekt Event. Fügen Sie einen Eintrag hinzu, um anzugeben, welches Ziel aus der Liste destinations das Ereignis empfangen soll. Weitere Informationen zum Definieren eines Destination und zum Ermitteln der Produktziel-ID finden Sie unter Ziele und Header konfigurieren.
id	transaction_id	Dieser Wert wird zum Deduplizieren von Conversion-Ereignissen verwendet. Weitere Informationen
timestamp	event_timestamp	Erforderlich. In der ECAPI wird für Zeitstempel das Unix-Epochenformat (Ganzzahl) verwendet. Bei der Zuordnung zur Data Manager API muss das Feld event_timestamp in eines der folgenden Formate konvertiert werden: Wenn Sie das JSON-Format verwenden, legen Sie einen Wert im RFC 3339-Format fest. Wenn Sie Protocol Buffers verwenden, nutzen Sie ein Timestamp und legen Sie die Felder seconds und (optional) nanoseconds fest. Weitere Informationen finden Sie unter Zeitstempelformat.
event_type/custom_event	event_name	Das kann ein empfohlener Ereignisname (z. B. purchase) oder ein benutzerdefinierter Ereignisname sein. Weitere Informationen finden Sie unter Standardereignisnamen.
user_data	user_data	Wird dem UserData-Objekt zugeordnet, das eine Liste von UserIdentifier-Objekten akzeptiert.
value	conversion_value	Wird direkt als Double oder Float abgebildet, das den Geldwert der Conversion darstellt.
currency_code	currency	Ordnen Sie einen dreistelligen Währungscode in Großbuchstaben zu (z. B. USD).
source	event_source	Legen Sie einen Wert aus dem Enum EventSource fest.
properties	cart_data custom_variables additional_event_parameters	Artikel auf Transaktionsebene können dem Array cart_data.items im Objekt CartData zugeordnet werden. Die Data Manager API unterstützt mehrere optionale Merchant Center-Felder für Produkte, die in Merchant Center-Konten vorhanden sind. Wenn Ihr Ziel eine Google Ads-Conversion-Aktion ist, können Sie auch zusätzliche benutzerdefinierte Parameter im Feld custom_variables als Liste von CustomVariable-Objekten angeben. Wenn Ihr Ziel ein Google Analytics-Datenstream ist, können Sie dem Feld additional_event_parameters eine Liste von AdditionalEventParameter-Objekten hinzufügen, um zusätzliche Ereignisparameter einzuschließen.
ext	Kein Äquivalent

Zuordnung von Nutzerdatenobjekten

Tipp :Weitere Informationen dazu, welche Kennungen für die einzelnen Ziele und Anwendungsfälle erforderlich und empfohlen sind, finden Sie im Abschnitt Daten in Event-Objekte umwandeln im Leitfaden zum Senden von Ereignissen.

In der Data Manager API akzeptiert das Feld user_data des Event-Objekts ein UserData-Objekt. Hier wird eine Liste von UserIdentifier-Objekten erwartet, die einzelne Nutzer-IDs wie E-Mail-Adressen, Telefonnummern oder Adresskomponenten enthalten können.

ECAPI (user_data)	Data Manager API (Event)	Hinweise
customer_identifier	user_id (Google Analytics)	Bei Google Analytics-Ereignissen steht das Feld user_id für eine Nutzer-ID. Die Data Manager API unterstützt keine generischen Kunden-ID-Felder für andere Ziele.
uids	Kein Äquivalent	Die Data Manager API unterstützt kein strukturiertes uids-Array mit Agent-Typen und ‑Domains.
customer_segments	user_properties	Karte nach UserProperties auf der Event.
email_address	user_data.user_identifiers[].email_address	Auf die formatierte und gehashte E-Mail-Adresse festgelegt. Sie können die gehashte E‑Mail-Adresse auch verschlüsseln.
phone_numbers	user_data.user_identifiers[].phone_number	Auf die formatierte und gehashte Telefonnummer festgelegt. Sie können die gehashte Telefonnummer auch verschlüsseln.
utcoffset	Kein Äquivalent	Wenn Sie das JSON-Format verwenden, können Sie den Zeitzonenversatz direkt im RFC 3339-String event_timestamp angeben. Wenn Sie Protocol Buffers verwenden, können Sie Hilfsfunktionen wie Timestamps.parse(String) verwenden, um die Zeitzonenkonvertierung in Sekunden und Nanosekunden zu verarbeiten. Weitere Informationen finden Sie unter Zeitstempelformat.
address	user_data.user_identifiers[].address	Wird einem AddressInfo-Objekt zugeordnet. Weitere Informationen finden Sie unter Zuordnung von Adressobjekten.
gpp_string	Kein Äquivalent	Die Einwilligung muss dem Consent-Objekt auf Anfrage- oder Ereignisebene zugeordnet werden. Weitere Informationen
gpp_sid	Kein Äquivalent	Die Einwilligung muss dem Consent-Objekt auf Anfrage- oder Ereignisebene zugeordnet werden. Weitere Informationen
mmt_only	Kein Äquivalent
click_id	ad_identifiers.gclid	Ordnen Sie die Google-Klick-ID (gclid) zu. Weitere Informationen finden Sie unter AdIdentifiers.
impression_id	ad_identifiers.impression_id	Weitere Informationen finden Sie unter AdIdentifiers.
event_ip_address	event_device_info.ip_address	Eine Liste der verfügbaren Felder finden Sie unter DeviceInfo.
event_user_agent	event_device_info.user_agent	Eine Liste der verfügbaren Felder finden Sie unter DeviceInfo.
ifa	ad_identifiers.mobile_device_id	Zuordnung zur ID für mobile Werbung (IDFA unter iOS, AdID unter Android). Weitere Informationen finden Sie unter AdIdentifiers.
landing_ip_address	ad_identifiers.landing_page_device_info.ip_address	Eine Liste der verfügbaren Felder finden Sie unter DeviceInfo.
landing_user_agent	ad_identifiers.landing_page_device_info.user_agent	Eine Liste der verfügbaren Felder finden Sie unter DeviceInfo.
age_range	Kein Äquivalent
gender	Kein Äquivalent
ext	Kein Äquivalent

Adressobjektzuordnung

ECAPI (address)	Data Manager API (AddressInfo)	Hinweise
first_name	given_name	Wird dem Feld given_name in AddressInfo zugeordnet. Halten Sie sich an die Formatierungs- und Hashing-Richtlinien. Sie können auch die gehashten Attribute einer Adresse verschlüsseln.
last_name	family_name	Wird dem Feld family_name in AddressInfo zugeordnet. Halten Sie sich an die Formatierungs- und Hashing-Richtlinien. Sie können auch die gehashten Attribute einer Adresse verschlüsseln.
street	Kein Äquivalent	Wird in der Data Manager API nicht unterstützt
city	Kein Äquivalent	Wird in der Data Manager API nicht unterstützt
state	Kein Äquivalent	Wird in der Data Manager API nicht unterstützt
country_code	region_code	Nicht hashen: Wird dem Feld region_code in AddressInfo zugeordnet. Beachten Sie die Formatierungsrichtlinien.
postal_code	postal_code	Nicht hashen: Wird dem Feld postal_code in AddressInfo zugeordnet. Beachten Sie die Formatierungsrichtlinien.
address_type	Kein Äquivalent	Wird in der Data Manager API nicht unterstützt
ext	Kein Äquivalent

Zuordnung von Artikelobjekten

Tipp :Weitere Informationen dazu, welche Felder in Warenkorbdaten für die einzelnen Anwendungsfälle für die Ereignisaufnahme enthalten sein müssen, finden Sie im Abschnitt Warenkorbdaten hinzufügen im Leitfaden zum Senden von Ereignissen.

ECAPI (item)	Data Manager API (Item)	Hinweise
id	item_id	Erforderlich für Google Analytics-Ereignisse. Auf eine standardmäßige, eindeutige Kennung für den Artikel festgelegt.
Kein Äquivalent	merchant_product_id	Erforderlich für Floodlight-Conversions und Google Ads-Conversions mit Warenkorbdaten. Wird auf die Produkt-ID im Merchant Center-Konto festgelegt.
name	additional_item_parameters	Karte als item_name in der Liste additional_item_parameters.
price	unit_price
discount	additional_item_parameters oder custom_variables	Ordnen Sie sie als discount in additional_item_parameters (für Google Analytics) oder als benutzerdefinierte Variable in custom_variables (für Google Ads) zu.
quantity	quantity	Konvertieren Sie den float-Wert in eine Ganzzahl (int64).
brand	additional_item_parameters	Karte als item_brand in der Liste additional_item_parameters.
affiliation	additional_item_parameters	Karte als affiliation in der Liste additional_item_parameters.
category	additional_item_parameters	Karte als item_category in der Liste additional_item_parameters.
cattax	Kein Äquivalent
item_coupon	additional_item_parameters	Karte als coupon in der Liste additional_item_parameters.
item_list_id	additional_item_parameters	Karte als item_list_id in der Liste additional_item_parameters.
item_list_name	additional_item_parameters	Karte als item_list_name in der Liste additional_item_parameters.
item_item_variant	additional_item_parameters	Karte als item_variant in der Liste additional_item_parameters.
item_location_id	additional_item_parameters	Karte als location_id in additional_item_parameters.
ext	Kein Äquivalent

Standardereignisnamen

ECAPI-Standardereignisse entsprechen weitgehend den Google Analytics-Namenskonventionen.

• Wenn Sie Ereignisse an einen Google Analytics-Datenstream senden, ist das Feld event_name erforderlich.
• In der Referenz zu empfohlenen Google Analytics-Ereignissen finden Sie für jedes Ereignis zugehörige Felder, Parameter und Beispielanfragen für die Data Manager API-Erfassung.
• Sie können auch benutzerdefinierte Ereignisse senden, sofern sie den Regeln für Ereignisnamen entsprechen.

Die meisten ECAPI-Standardereignisse (z. B. purchase, add_to_cart, begin_checkout, search und refund) haben denselben Ereignisnamen wie die von Google Analytics empfohlenen Ereignisse. Es gibt jedoch einige Ausnahmen, in denen in Google Analytics die Gegenwartsform anstelle der Vergangenheitsform verwendet wird:

• viewed_item wird view_item zugeordnet.
• viewed_item_list wird view_item_list zugeordnet.
• viewed_cart wird view_cart zugeordnet.

Beispielanfragen

Auf den folgenden Tabs sehen Sie einen Vergleich zwischen der Nutzlast eines ECAPI-Conversion-Ereignisses und seiner Darstellung als gültige Data Manager API-IngestEventsRequest.

ECAPI

Hier ist eine Beispiel-JSON-Nutzlast, die der ECAPI-Spezifikation entspricht.

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

Hier sehen Sie ein Beispiel für IngestEventsRequest für die formatierten, gehashten und codierten Ereignisdaten. Dies gilt für ein Google Ads-Ziel, wie durch den Kontotyp GOOGLE_ADS im Ziel angegeben.

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