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ı üst düzey bir görünümle sunulmaktadır:
| ECAPI | Data Manager API | |
|---|---|---|
| Tekilleştirme | id (etkinlik kimliği) parametresine bağlıdır. |
transaction_id 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, etkinlikleri tek bir istekte birden fazla hedefe yönlendirmeyi de destekler. Daha fazla bilgi için Hedefleri ve üstbilgileri yapılandırma başlıklı makaleyi inceleyin. |
| Gizlilik ve rıza alanları | Global Privacy Platform (GPP) rıza 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 her bir alanın Data Manager API tarafından kabul edilen alanlara nasıl dönüştürüleceğ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 için Etkinlik gönderme kılavuzlarında Google'ın çok kaynaklı verileri nasıl işlediğini 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 maddi değerini temsil eden bir double veya float olarak doğrudan eşleyin. |
currency_code |
currency |
Üç harfli büyük harfli bir para birimi koduyla (ör. USD) eşleyin. |
source |
event_source |
EventSource enum'undan 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ı verileri nesne 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 bireysel 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. Data Manager API, 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 arabellekleri kullanıyorsanız saat dilimi dönüşümünü saniye ve nanosaniye olarak işlemek için Timestamps.parse(String) gibi hizmet işlevlerini 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 rıza genel bakış bölümüne bakın. |
gpp_sid |
Eşdeğeri yok | İzinleri istek düzeyindeki veya etkinlik düzeyindeki Consent nesnesiyle eşleyin. Gizlilik ve rıza genel bakış bölümüne bakın. |
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'deki family_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. |
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şturma uygulamayın. AddressInfo'deki region_code alanıyla eşlenir. Biçimlendirme kurallarına uyun. |
postal_code |
postal_code |
Karma oluşturma uygulamayı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 eşleyin. |
price |
unit_price |
|
discount |
additional_item_parameters veya custom_variables |
additional_item_parameters içinde discount (Google Analytics için) veya custom_variables içinde özelleştirilebilen değişken (Google Ads için) 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 eşleyin. |
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 içinde location_id olarak eşleyin. |
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 Veri Yöneticisi API'si besleme 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_cartile eşleşiyor
Örnek istekler
Aşağıdaki sekmelerde, ECAPI dönüşüm etkinliği yükü ile geçerli bir Data Manager API'si olarak temsili 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
}
]
}
}
]
}