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 besleme şemasıyla eşlemesine yardımcı olur.
Genel Bakış
ECAPI, pazarlamayla ilgili etkinliklerin ve dönüşümlerin yapısını tanımlayan, platformdan bağımsız, açık kaynaklı bir veri standardıdır.
Aşağıdaki tabloda, ECAPI'nin temel özellikleri ve tasarım ilkelerinin Data Manager API 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 sürümünü kullanır |
| Etkinlik yönlendirme | Etkinlik yükündeki data_set_id alanı, verilerin hedefini gösterir. |
İ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 Hedefleri ve başlıkları yapılandırma başlıklı makaleyi inceleyin. |
| Gizlilik ve rıza 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. Consent nesnesinde izin alanlarını ayarlayın.
İzni istek düzeyinde (istekteki tüm etkinlikler için geçerlidir) veya etkinlik düzeyinde (ayrı etkinlikler için farklı izin ayarları belirlemenize 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 |
|
Hedefleri aşağıdaki seviyelerde tanımlayabilirsiniz:
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 |
Dönüşüm etkinliklerini tekilleştirir. Google Ads, Google Analytics ve Floodlight ile ilgili Etkinlik gönderme kılavuzlarındaki Google'ın çok kaynaklı verileri işleme şekli başlıklı bölümü inceleyin. |
timestamp |
event_timestamp |
Zorunlu. ECAPI, zaman damgaları için Unix epoch biçimini (tam sayı) kullanır.
Data Manager API ile eşleme yaparken event_timestamp alanını aşağıdaki biçimlerden birine dönüştürü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ı başlıklı makaleyi inceleyin. |
user_data |
user_data |
UserIdentifier nesnelerinin listesini kabul eden UserData nesnesiyle eşlenir. |
value |
conversion_value |
Dönüşümün parasal değerini temsil eden bir ç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 |
|
İşlem düzeyindeki öğeleri CartData nesnesindeki cart_data.items dizisiyle eşleyin. Data Manager API, Merchant Center hesaplarında bulunan ürünler için isteğe bağlı birkaç Merchant Center alanını destekler.
Hedefiniz bir Google Ads dönüşüm işlemine aitse custom_variables alanına CustomVariable nesnelerinin 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şlemesi
Data Manager API'de, Event nesnesindeki user_data alanı UserData nesnesini kabul eder. Bu, e-posta adresleri, telefon numaraları veya adres bileşenleri gibi ayrı kullanıcı kimlikleri içerebilen UserIdentifier nesnelerinin bir listesini bekler:
ECAPI (user_data) |
Data Manager API (Event) |
Notlar |
|---|---|---|
customer_identifier |
user_id (Google Analytics) |
Google Analytics etkinlikleri için user_id alanı, User-ID'yi temsil eder. Veri Yöneticisi API'si, diğer hedefler için genel müşteri kimliği alanlarını desteklemez. |
uids |
Eşdeğeri yok | Data Manager API, temsilci türlerini ve alan adlarını içeren yapılandırılmış bir uids dizisini desteklemez. |
customer_segments |
user_properties |
Event sayfasında UserProperties ile eşleyin. |
email_address |
user_data.user_identifiers[].email_address |
Biçimlendirilmiş ve karma oluşturma işlemi uygulanmış e-posta adresine ayarlayın. Karma oluşturma işlemi uygulanmış e-posta adresini şifreleyebilirsiniz. |
phone_numbers |
user_data.user_identifiers[].phone_number |
Biçimlendirilmiş ve karma oluşturma işlemi uygulanmış telefon numarasına ayarlanır. Karma oluşturma işlemi uygulanmış telefon numarasını ş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 arabelleklerini 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 |
Bir AddressInfo nesnesiyle eşlenir. Adres nesnesi eşleme bölümüne bakın. |
gpp_string |
Eşdeğeri yok | İzinleri istek düzeyindeki veya etkinlik düzeyindeki Consent nesnesiyle eşleyin. Gizlilik ve izin genel bakış başlıklı makaleyi inceleyin. |
gpp_sid |
Eşdeğeri yok | İzni istek düzeyinde veya etkinlik düzeyinde Consent nesnesiyle eşleyin. Gizlilik ve izin genel bakış başlıklı makaleyi inceleyin. |
mmt_only |
Eşdeğeri yok | |
click_id |
ad_identifiers.gclid |
Google Tıklama Kimliği (gclid) ile 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 tanımlayıcıyla (iOS'te IDFA, Android'de AdID) eşleştirin. 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'deki given_name alanıyla eşlenir. Biçimlendirme ve karma oluşturma yönergelerini uygulayın. 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 | Data Manager API'de 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'deki 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 gereklidir. Öğe için standart ve benzersiz bir tanımlayıcıya 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 ayarlanır. |
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 eşleyin. |
affiliation |
additional_item_parameters |
additional_item_parameters listesinde affiliation olarak eşleyin. |
category |
additional_item_parameters |
additional_item_parameters listesinde item_category olarak eşleyin. |
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 eşleyin. |
item_list_name |
additional_item_parameters |
additional_item_parameters listesinde item_list_name olarak eşleyin. |
item_item_variant |
additional_item_parameters |
additional_item_parameters listesinde item_variant olarak eşleyin. |
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.
Etkinlikleri bir Google Analytics veri akışına gönderiyorsanız
event_namealanı zorunludur.Her etkinlik için ilişkili alanlar, parametreler ve örnek Data Manager API alım istekleri hakkında bilgi edinmek üzere Google Analytics önerilen etkinlikler referansını inceleyin.
Etkinlik adlandırma kurallarına uygun özel etkinlikler de gönderebilirsiniz.
Çoğu ECAPI standart etkinliği (ör. purchase, add_to_cart, begin_checkout, search ve refund), Google Analytics tarafından önerilen etkinliklerle aynı etkinlik adına sahiptir. Ancak Google Analytics'in geçmiş zaman yerine şimdiki zamanı kullandığı birkaç istisna vardır:
viewed_item,view_itemile eşleşiyorviewed_item_list,view_item_listile eşleşiyorviewed_cart-view_cart
Ö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 oluşturma işlemi uygulanmış ve kodlanmış etkinlik verileri için örnek bir IngestEventsRequest aşağıda verilmiştir. Hedefteki GOOGLE_ADS hesap türü, isteğin bir Google Ads hedefini hedeflediğini gösterir:
{
"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
}
]
}
}
]
}