ECAPI spesifikasyon eşlemesi

Bu kılavuz, IAB Tech Lab Event and Conversion API (ECAPI) spesifikasyonunu kullanan geliştiricilerin etkinlik ve dönüşüm verilerini Data Manager API etkinlik alımı şeması ile eşlemesine yardımcı olur.

Genel Bakış

ECAPI, pazarlamayla ilgili etkinliklerin ve dönüşümlerin nasıl yapılandırılacağını tanımlamak için tasarlanmış, platformdan bağımsız ve açık kaynaklı bir veri standardıdır.

Aşağıdaki tabloda, ECAPI'nin temel özellikleri ve tasarım ilkelerinin Veri Yöneticisi API'si ile karşılaştırmasına dair üst düzey bir görünüm sunulmaktadır.

ECAPI Data Manager API
Tekilleştirme id (etkinlik kimliği) öğesine bağlıdır. transaction_id özelliğini kullanır.
Etkinlik yönlendirme Verilerin hedefi, etkinlik yükündeki data_set_id alanı ile belirtilir. İsteğin destinations alanı, etkinliklerin hedeflerini tanımlar.

Data Manager API, etkinliklerin tek bir istekte birden fazla hedefe yönlendirilmesini de destekler.

Daha fazla bilgi için hedefler kılavuzuna bakın.
Gizlilik ve kullanıcı rızası alanları Global Privacy Platform (GPP) izin dizeleri Data Manager API, Global Privacy Platform (GPP) kullanıcı rızası dizelerini kabul etmez veya ayrıştırmaz. İzin alanları, Consent nesnesinde ayarlanmalıdır.

İzni istek düzeyinde (istekteki tüm etkinlikler için geçerlidir) veya etkinlik düzeyinde (tek tek etkinlikler için farklı izin ayarları belirtmenize olanak tanır) ayarlayabilirsiniz.

Yapısal alan eşleme

Aşağıdaki eşleme tabloları, ECAPI spesifikasyonundaki alanların Data Manager API'si tarafından kabul edilen alanlara nasıl çevrildiğini tanımlar.

Etkinlik nesnesi eşleme

ECAPI (event) Data Manager API (Event) Notlar
data_set_id
  • destinations[].product_destination_id (İstek düzeyi)
  • destination_references (Etkinlik düzeyi)
 Aşağıdaki düzeylerde tanımlanabilir:
  • İstek düzeyi (zorunlu): destinations listesini IngestEventsRequest içinde belirtin.
  • Etkinlik düzeyi: Event nesnesindeki destination_references alanını kullanın. destinations listesindeki hangi hedefin etkinliği alacağını belirtmek için bir giriş ekleyin.

Destination tanımlama ve ürün hedef kimliğini belirleme hakkında daha fazla bilgi için Hedefleri ve başlıkları yapılandırma başlıklı makaleyi inceleyin.
id transaction_id Bu değer, dönüşüm etkinliklerinin tekilleştirilmesi için kullanılır. Daha fazla bilgi
timestamp event_timestamp Zorunlu. ECAPI, zaman damgaları için Unix sıfır zaman biçimini (tam sayı) kullanır. Data Manager API'ye eşleme yapılırken event_timestamp alanı aşağıdaki biçimlerden birine dönüştürülmelidir:
  • JSON biçimi kullanılıyorsa RFC 3339 biçiminde bir değere ayarlayın.
  • Protocol buffer kullanıyorsanız Timestamp kullanın ve seconds ile (isteğe bağlı olarak) nanoseconds alanlarını ayarlayın.

Ayrıntılar için Zaman damgası biçimi bölümüne bakın.
event_type/custom_event event_name Bu, önerilen bir etkinlik adı (örneğin, purchase) veya özel bir etkinlik adı olabilir. Ayrıntılar için Standart etkinlik adları bölümüne bakın.
user_data user_data UserData nesnesine eşlenir. Bu nesne, UserIdentifier nesnelerinin listesini kabul eder.
value conversion_value Dönüşümün parasal değerini temsil eden çift veya kayan nokta olarak doğrudan eşleyin.
currency_code currency Üç harfli büyük harf para birimi koduyla eşleyin (örneğin, USD).
source event_source EventSource enum'ından bir değere ayarlanır.
properties
  • cart_data
  • custom_variables
  • additional_event_parameters
 İşlem düzeyindeki öğeler, CartData nesnesindeki cart_data.items dizisine eşlenebilir. Veri Yöneticisi API'si, Merchant Center hesaplarında bulunan ürünler için çeşitli isteğe bağlı Merchant Center alanlarını destekler.

Hedefiniz bir Google Ads dönüşüm işlemiyse custom_variables alanına CustomVariable nesneleri listesi olarak ek özel parametreler de ekleyebilirsiniz.

Hedefiniz bir Google Analytics veri akışıysa additional_event_parameters alanına AdditionalEventParameter nesnelerinin listesi olarak ek etkinlik parametreleri ekleyebilirsiniz.
ext Eşdeğeri yok

Kullanıcı verisi nesnesi eşleme

Veri Yöneticisi API'sinde, Event nesnesindeki user_data alanı bir UserData nesnesini kabul eder. Bu yöntem, e-posta adresleri, telefon numaraları veya adres bileşenleri gibi ayrı kullanıcı tanımlayıcıları içerebilen UserIdentifier nesnelerinin listesini bekler.

ECAPI (user_data) Data Manager API (Event) Notlar
customer_identifier user_id (Google Analytics) Google Analytics etkinliklerinde user_id alanı bir User-ID'yi temsil eder. Data Manager API'si, diğer hedefler için genel müşteri kimliği alanlarını desteklemez.
uids Eşdeğeri yok Veri Yöneticisi API'si, aracı türlerini ve alanlarını içeren yapılandırılmış uids diziyi desteklemez.
customer_segments user_properties Event üzerindeki UserProperties konumunun haritası.
email_address user_data.user_identifiers[].email_address Biçimlendirilmiş ve karma oluşturulmuş e-posta adresine ayarlayın. Ayrıca karma oluşturulmuş e-posta adresini şifreleyebilirsiniz.
phone_numbers user_data.user_identifiers[].phone_number Biçimlendirilmiş ve karma oluşturma işlemi uygulanmış telefon numarası olarak ayarlayın. Karma oluşturma işlemi uygulanmış telefon numarasını da şifreleyebilirsiniz.
utcoffset Eşdeğeri yok JSON biçimini kullanıyorsanız saat dilimi farkını doğrudan RFC 3339 event_timestamp dizesinde belirtebilirsiniz.
Protokol arabellekleri kullanıyorsanız saat dilimi dönüşümünü saniye ve nanosaniye cinsinden işlemek için Timestamps.parse(String) gibi yardımcı işlevleri kullanabilirsiniz.
Ayrıntılar için Zaman damgası biçimi bölümüne bakın.
address user_data.user_identifiers[].address AddressInfo nesnesiyle eşlenir. Adres nesnesi eşleme bölümüne bakın.
gpp_string Eşdeğeri yok İzin, istek düzeyinde veya etkinlik düzeyinde Consent nesnesiyle eşlenmelidir. Gizlilik ve izinlere genel bakış başlıklı makaleyi inceleyin.
gpp_sid Eşdeğeri yok İzin, istek düzeyinde veya etkinlik düzeyinde Consent nesnesiyle eşlenmelidir. Gizlilik ve izinlere genel bakış başlıklı makaleyi inceleyin.
mmt_only Eşdeğeri yok
click_id ad_identifiers.gclid Google tıklama kimliğiyle (gclid) eşleyin. Daha fazla bilgi için AdIdentifiers bölümüne bakın.
impression_id ad_identifiers.impression_id Daha fazla bilgi için AdIdentifiers sayfasına bakın.
event_ip_address event_device_info.ip_address Kullanılabilir alanlar için DeviceInfo bölümüne bakın.
event_user_agent event_device_info.user_agent Kullanılabilir alanlar için DeviceInfo bölümüne bakın.
ifa ad_identifiers.mobile_device_id Reklamverenler için mobil kimlikle (iOS'te IDFA, Android'de AdID) eşleyin. Daha fazla bilgi için AdIdentifiers sayfasına bakın.
landing_ip_address ad_identifiers.landing_page_device_info.ip_address Kullanılabilir alanlar için DeviceInfo bölümüne bakın.
landing_user_agent ad_identifiers.landing_page_device_info.user_agent Kullanılabilir alanlar için DeviceInfo bölümüne bakın.
age_range Eşdeğeri yok
gender Eşdeğeri yok
ext Eşdeğeri yok

Adres nesnesi eşleme

ECAPI (address) Data Manager API (AddressInfo) Notlar
first_name given_name AddressInfo'daki given_name alanıyla eşlenir. Biçimlendirme ve karma oluşturma kurallarına uyun. Bir adresin karma oluşturma işlemi uygulanmış özelliklerini de şifreleyebilirsiniz.
last_name family_name AddressInfo'daki family_name alanıyla eşlenir. Biçimlendirme ve karma oluşturma kurallarına uyun. Bir adresin karma oluşturma işlemi uygulanmış özelliklerini de şifreleyebilirsiniz.
street Eşdeğeri yok Veri Yöneticisi API'sinde desteklenmez.
city Eşdeğeri yok Veri Yöneticisi API'sinde desteklenmez.
state Eşdeğeri yok Veri Yöneticisi API'sinde desteklenmez.
country_code region_code Karma oluşturmayın. AddressInfo'daki region_code alanıyla eşlenir. Biçimlendirme kurallarına uyun.
postal_code postal_code Karma oluşturmayın. AddressInfo'daki postal_code alanıyla eşlenir. Biçimlendirme kurallarına uyun.
address_type Eşdeğeri yok Veri Yöneticisi API'sinde desteklenmez.
ext Eşdeğeri yok

Öğe nesnesi eşleme

ECAPI (item) Data Manager API (Item) Notlar
id item_id Google Analytics etkinlikleri için zorunludur. Öğe için standart ve benzersiz bir tanımlayıcı olarak ayarlanır.
Eşdeğeri yok merchant_product_id Floodlight dönüşümleri ve alışveriş sepeti verileriyle Google Ads dönüşümleri için zorunludur. Merchant Center hesabındaki ürün kimliğine ayarlayın.
name additional_item_parameters additional_item_parameters listesinde item_name olarak harita.
price unit_price
discount additional_item_parameters veya custom_variables additional_item_parameters (Google Analytics için) içinde discount olarak veya custom_variables (Google Ads için) içinde özel değişken olarak eşleyin.
quantity quantity float değerini tam sayıya (int64) dönüştürün.
brand additional_item_parameters additional_item_parameters listesinde item_brand olarak harita.
affiliation additional_item_parameters additional_item_parameters listesinde affiliation olarak harita.
category additional_item_parameters additional_item_parameters listesinde item_category olarak harita.
cattax Eşdeğeri yok
item_coupon additional_item_parameters additional_item_parameters listesinde coupon olarak harita.
item_list_id additional_item_parameters additional_item_parameters listesinde item_list_id olarak harita.
item_list_name additional_item_parameters additional_item_parameters listesinde item_list_name olarak harita.
item_item_variant additional_item_parameters additional_item_parameters listesinde item_variant olarak harita.
item_location_id additional_item_parameters additional_item_parameters bölgesindeki location_id haritası.
ext Eşdeğeri yok

Standart etkinlik adları

ECAPI standart etkinlikleri, Google Analytics adlandırma kurallarıyla büyük ölçüde uyumludur.

Çoğu ECAPI standart etkinliği (ör. purchase, add_to_cart, begin_checkout, search ve refund), Google Analytics'in önerdiği etkinliklerle aynı etkinlik adına sahiptir. Ancak Google Analytics'in geçmiş zaman yerine geniş zaman kullandığı birkaç istisna vardır:

  • viewed_item, view_item ile eşlenir.
  • viewed_item_list, view_item_list ile eşlenir.
  • viewed_cart, view_cart ile eşlenir.

Örnek istekler

Aşağıdaki sekmelerde, bir ECAPI dönüşüm etkinliği yükü ile bunun geçerli bir Data Manager API'si olarak gösterimi arasındaki karşılaştırma gösterilmektedir. IngestEventsRequest

ECAPI

ECAPI spesifikasyonuna uygun örnek bir JSON yükü aşağıda verilmiştir.

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

Biçimlendirilmiş, karma uygulanmış ve kodlanmış etkinlik verileri için örnek bir IngestEventsRequest aşağıda verilmiştir. Bu, hedefteki GOOGLE_ADS hesap türünün gösterdiği gibi bir Google Ads hedefi içindir.

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