ECAPI-Spezifikationszuordnung

In diesem Leitfaden wird Entwicklern, die die Spezifikation der Event and Conversion API (ECAPI) des IAB Tech Lab verwenden, erläutert, 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 die Struktur von marketingbezogenen Ereignissen und Conversions definiert.

Die folgende Tabelle bietet einen allgemeinen Überblick über die wichtigsten Attribute und Designprinzipien der ECAPI im Vergleich zur Data Manager API:

ECAPI Data Manager API
Deduplizierung Basiert auf id (Ereignis-ID) Basiert auf transaction_id
Ereignisrouting Das Feld data_set_id in der Ereignisnutzlast gibt das Ziel der Daten an. 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 einzelnen Anfrage.

Weitere Informationen finden Sie unter Ziele und Header konfigurieren.
Felder für Datenschutz und Einwilligung Einwilligungsstrings der Global Privacy Platform (GPP) Die Data Manager API akzeptiert oder parst keine Einwilligungs-Strings der Global Privacy Platform (GPP). Legen Sie die Einwilligungsfelder im Consent-Objekt fest.

Sie können die Einwilligung entweder auf Anfrageebene (gilt für alle Ereignisse in der Anfrage) oder auf Ereignisebene festlegen (ermöglicht die Angabe unterschiedlicher Einwilligungseinstellungen für einzelne Ereignisse).

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:

Zuordnung von Ereignisobjekten

ECAPI (event) Data Manager API (Event) Hinweise
data_set_id
  • destinations[].product_destination_id (Anfrageebene)
  • destination_references (Ereignisebene)
 Sie können Ziele auf den folgenden Ebenen definieren:
  • Anfrageebene (erforderlich): Geben Sie die Liste der destinations in der IngestEventsRequest an.
  • Ereignisebene (optional): Verwenden Sie das Feld destination_references im Objekt Event. Fügen Sie einen Eintrag hinzu, um anzugeben, welches Ziel aus der destinations-Liste das Ereignis empfangen soll.

Weitere Informationen zum Definieren einer Destination und zum Bestimmen der Produktziel-ID findest du unter Ziele und Header konfigurieren.
id transaction_id Conversion-Ereignisse werden dedupliziert. Weitere Informationen finden Sie im Abschnitt Wie Google mit Daten aus mehreren Quellen umgeht in den Leitfäden zum Senden von Ereignissen für Google Ads, Google Analytics und Floodlight.
timestamp event_timestamp Erforderlich. ECAPI verwendet das Unix-Epochenformat (Ganzzahl) für Zeitstempel. Wenn Sie die Zuordnung zur Data Manager API vornehmen, konvertieren Sie das Feld event_timestamp in eines der folgenden Formate:
  • 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 zugeordnet, das den Geldwert der Conversion darstellt.
currency_code currency Ordnen Sie den Wert einem dreistelligen Währungscode in Großbuchstaben zu (z. B. USD).
source event_source Auf einen Wert aus der Aufzählung EventSource festgelegt.
properties
  • cart_data
  • custom_variables
  • additional_event_parameters
 Ordnen Sie Artikel auf Transaktionsebene dem Array cart_data.items im Objekt CartData zu. 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 im Feld custom_variables auch zusätzliche benutzerdefinierte Parameter als Liste von CustomVariable-Objekten angeben.

Wenn Ihr Ziel ein Google Analytics-Datenstream ist, können Sie im Feld additional_event_parameters zusätzliche Ereignisparameter als Liste von AdditionalEventParameter-Objekten angeben.
ext Kein Äquivalent

Zuordnung von Nutzerdatenobjekten

In der Data Manager API akzeptiert das Feld user_data im Objekt Event 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 User-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 Agententypen und Domains.
customer_segments user_properties Ordnen Sie UserProperties dem Event zu.
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 Legen Sie die formatierte und gehashte Telefonnummer fest. Sie können die gehashte Telefonnummer auch verschlüsseln.
utcoffset Kein Äquivalent Wenn Sie das JSON-Format verwenden, können Sie die Zeitzonenverschiebung direkt im RFC 3339-event_timestamp-String 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 Ordnen Sie die Einwilligung dem Objekt Consent auf Anfrage- oder Ereignisebene zu. Übersicht zu Datenschutz und Einwilligung
gpp_sid Kein Äquivalent Ordnen Sie die Einwilligung dem Objekt Consent auf Anfrage- oder Ereignisebene zu. Übersicht zu Datenschutz und Einwilligung
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 Verfügbare Felder finden Sie unter DeviceInfo.
event_user_agent event_device_info.user_agent Verfügbare Felder finden Sie unter DeviceInfo.
ifa ad_identifiers.mobile_device_id Zuordnung zur mobilen Kennung für Werbetreibende (IDFA unter iOS, AdID unter Android) Weitere Informationen finden Sie unter AdIdentifiers.
landing_ip_address ad_identifiers.landing_page_device_info.ip_address Verfügbare Felder finden Sie unter DeviceInfo.
landing_user_agent ad_identifiers.landing_page_device_info.user_agent Verfügbare Felder finden Sie unter DeviceInfo.
age_range Kein Äquivalent
gender Kein Äquivalent
ext Kein Äquivalent

Zuordnung von Adressobjekten

ECAPI (address) Data Manager API (AddressInfo) Hinweise
first_name given_name Wird dem Feld given_name in AddressInfo zugeordnet. Folgen Sie den Formatierungs- und Hash-Richtlinien. Sie können auch die gehashten Attribute einer Adresse verschlüsseln.
last_name family_name Wird dem Feld family_name in AddressInfo zugeordnet. Folgen Sie den Formatierungs- und Hash-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. Halten Sie sich an die Formatierungsrichtlinien.
postal_code postal_code Nicht hashen: Entspricht dem Feld postal_code in AddressInfo. Beachten Sie die Formatierungsrichtlinien.
address_type Kein Äquivalent Wird in der Data Manager API nicht unterstützt.
ext Kein Äquivalent

Zuordnung von Elementobjekten

verfügbar sind.
ECAPI (item) Data Manager API (Item) Hinweise
id item_id Erforderlich für Google Analytics-Ereignisse. Wird auf eine standardmäßige, eindeutige Kennung für den Artikel festgelegt.
Kein Äquivalent merchant_product_id Erforderlich für Floodlight-Conversions und Google Ads-Anzeigen-Conversions mit Warenkorbdaten. Wird auf die Produkt-ID im Merchant Center-Konto festgelegt.
name additional_item_parameters Ordnen Sie es in der Liste additional_item_parameters als item_name zu.
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 Ordnen Sie es in der Liste additional_item_parameters als item_brand zu.
affiliation additional_item_parameters Ordnen Sie es in der Liste additional_item_parameters als affiliation zu.
category additional_item_parameters Ordnen Sie es in der Liste additional_item_parameters als item_category zu.
cattax Kein Äquivalent
item_coupon additional_item_parameters Karte als coupon in der Liste additional_item_parameters.
item_list_id additional_item_parameters Ordnen Sie es in der Liste additional_item_parameters als item_list_id zu.
item_list_name additional_item_parameters Ordnen Sie es in der Liste additional_item_parameters als item_list_name zu.
item_item_variant additional_item_parameters Ordnen Sie es in der Liste additional_item_parameters als item_variant zu.
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.

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 das Präsens anstelle des Perfekts 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ültiges IngestEventsRequest der Data Manager API:

ECAPI

Hier ist eine JSON-Beispielnutzlast, 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. Der Kontotyp GOOGLE_ADS im Ziel gibt an, dass die Anfrage auf ein Google Ads-Ziel verweist:

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