इस गाइड की मदद से, IAB Tech Lab Event and Conversion API (ECAPI) स्पेसिफ़िकेशन का इस्तेमाल करने वाले डेवलपर, अपने इवेंट और कन्वर्ज़न डेटा को Data Manager API के इवेंट डेटा डालने वाले स्कीमा से मैप कर सकते हैं.
खास जानकारी
ईसीएपीआई, एक ओपन-सोर्स डेटा स्टैंडर्ड है. यह किसी खास प्लैटफ़ॉर्म पर निर्भर नहीं करता. यह मार्केटिंग से जुड़े इवेंट और कन्वर्ज़न के स्ट्रक्चर को तय करता है.
यहां दी गई टेबल में, ECAPI के मुख्य एट्रिब्यूट और डिज़ाइन के सिद्धांतों की तुलना, Data Manager API से की गई है:
| ECAPI | Data Manager API | |
|---|---|---|
| डुप्लीकेट कॉपी हटाने की तकनीक | id (इवेंट आईडी) पर निर्भर है |
transaction_id पर निर्भर है |
| इवेंट रूटिंग | इवेंट पेलोड में मौजूद data_set_id फ़ील्ड से, डेटा के डेस्टिनेशन का पता चलता है. |
अनुरोध के destinations फ़ील्ड से, इवेंट के डेस्टिनेशन तय होते हैं.
Data Manager API की मदद से, एक ही अनुरोध में इवेंट को एक से ज़्यादा डेस्टिनेशन पर भेजा जा सकता है. ज़्यादा जानकारी के लिए, डेस्टिनेशन और हेडर कॉन्फ़िगर करना लेख पढ़ें. |
| निजता और सहमति वाले फ़ील्ड | Global Privacy Platform (GPP) की सहमति वाली स्ट्रिंग |
Data Manager API, Global Privacy Platform (GPP) की सहमति वाली स्ट्रिंग को स्वीकार या पार्स नहीं करता. Consent ऑब्जेक्ट में सहमति वाले फ़ील्ड सेट करें.
सहमति को अनुरोध के लेवल पर सेट किया जा सकता है. यह अनुरोध में मौजूद सभी इवेंट पर लागू होती है. इसके अलावा, इसे इवेंट के लेवल पर भी सेट किया जा सकता है. इससे आपको अलग-अलग इवेंट के लिए, सहमति की अलग-अलग सेटिंग तय करने की सुविधा मिलती है. |
स्ट्रक्चरल फ़ील्ड मैपिंग
यहां दी गई मैपिंग टेबल से पता चलता है कि ECAPI स्पेसिफ़िकेशन के अलग-अलग फ़ील्ड, Data Manager API के स्वीकार किए गए फ़ील्ड में कैसे ट्रांसलेट होते हैं:
इवेंट ऑब्जेक्ट की मैपिंग
ECAPI (event) |
Data Manager API (Event) |
नोट |
|---|---|---|
data_set_id |
|
डेस्टिनेशन को इन लेवल पर तय किया जा सकता है:
Destination को तय करने और प्रॉडक्ट के डेस्टिनेशन आईडी का पता लगाने के बारे में ज़्यादा जानने के लिए, डेस्टिनेशन और हेडर कॉन्फ़िगर करना लेख पढ़ें.
|
id |
transaction_id |
कन्वर्ज़न इवेंट की डुप्लीकेट कॉपी हटाता है. Google Ads, Google Analytics, और Floodlight के लिए, इवेंट भेजें गाइड में जाकर, Google, कई सोर्स से मिलने वाले डेटा को कैसे मैनेज करता है देखें. |
timestamp |
event_timestamp |
ज़रूरी है. ईसीएपीआई, टाइमस्टैंप के लिए Unix epoch फ़ॉर्मैट (पूर्णांक) का इस्तेमाल करता है.
Data Manager API से मैप करते समय, event_timestamp फ़ील्ड को इनमें से किसी एक फ़ॉर्मैट में बदलें:
ज़्यादा जानकारी के लिए, टाइमस्टैंप का फ़ॉर्मैट देखें. |
event_type / custom_event |
event_name |
यह सुझाए गए इवेंट का नाम (उदाहरण के लिए, purchase) या कस्टम इवेंट का नाम हो सकता है. ज़्यादा जानकारी के लिए, स्टैंडर्ड इवेंट के नाम देखें. |
user_data |
user_data |
यह UserData ऑब्जेक्ट से मैप करता है. यह ऑब्जेक्ट, UserIdentifier ऑब्जेक्ट की सूची स्वीकार करता है. |
value |
conversion_value |
कन्वर्ज़न की मॉनेटरी वैल्यू को दिखाने वाले डबल या फ़्लोट के तौर पर सीधे मैप करें. |
currency_code |
currency |
तीन अक्षरों वाले अपरकेस करंसी कोड से मैप करें. उदाहरण के लिए, USD. |
source |
event_source |
EventSource enum से किसी वैल्यू पर सेट करें. |
properties |
|
लेन-देन के लेवल पर मौजूद आइटम को CartData ऑब्जेक्ट में मौजूद cart_data.items कलेक्शन से मैप करें. Data Manager API, Merchant Center खातों में मौजूद प्रॉडक्ट के लिए, Merchant Center के कई वैकल्पिक फ़ील्ड के साथ काम करता है.
अगर आपका डेस्टिनेशन, Google Ads कन्वर्ज़न ऐक्शन है, तो custom_variables फ़ील्ड में CustomVariable ऑब्जेक्ट की सूची के तौर पर, अन्य कस्टम पैरामीटर भी शामिल किए जा सकते हैं.
अगर आपका डेस्टिनेशन Google Analytics डेटा स्ट्रीम है, तो additional_event_parameters फ़ील्ड में AdditionalEventParameter ऑब्जेक्ट की सूची के तौर पर, अन्य इवेंट पैरामीटर शामिल किए जा सकते हैं.
|
ext |
कोई मिलती-जुलती रिपोर्ट नहीं |
उपयोगकर्ता के डेटा ऑब्जेक्ट की मैपिंग
Data Manager API में, Event ऑब्जेक्ट पर मौजूद user_data फ़ील्ड, UserData ऑब्जेक्ट को स्वीकार करता है. इसमें UserIdentifier ऑब्जेक्ट की सूची होनी चाहिए. इसमें ईमेल पते, फ़ोन नंबर या पते के कॉम्पोनेंट जैसे यूज़र आइडेंटिफ़ायर शामिल हो सकते हैं:
ECAPI (user_data) |
Data Manager API (Event) |
नोट |
|---|---|---|
customer_identifier |
user_id (Google Analytics) |
Google Analytics इवेंट के लिए, user_id फ़ील्ड, यूज़र आईडी को दिखाता है. Data Manager API, अन्य डेस्टिनेशन के लिए सामान्य ग्राहक आईडी फ़ील्ड के साथ काम नहीं करता. |
uids |
कोई मिलती-जुलती रिपोर्ट नहीं | Data Manager API, एजेंट टाइप और डोमेन वाले स्ट्रक्चर्ड uids कलेक्शन के साथ काम नहीं करता. |
customer_segments |
user_properties |
Event पर UserProperties पर मैप करें. |
email_address |
user_data.user_identifiers[].email_address |
फ़ॉर्मैट और हैश किए गए ईमेल पते पर सेट करें. हैश किए गए ईमेल पते को एन्क्रिप्ट (सुरक्षित) भी किया जा सकता है. |
phone_numbers |
user_data.user_identifiers[].phone_number |
फ़ॉर्मैट और हैश किए गए फ़ोन नंबर पर सेट करें. हैश किए गए फ़ोन नंबर को एन्क्रिप्ट भी किया जा सकता है. |
utcoffset |
कोई मिलती-जुलती रिपोर्ट नहीं |
JSON फ़ॉर्मैट का इस्तेमाल करने पर, सीधे RFC 3339 event_timestamp स्ट्रिंग में टाइमज़ोन ऑफ़सेट की जानकारी दी जा सकती है.
अगर प्रोटोकॉल बफ़र का इस्तेमाल किया जा रहा है, तो टाइमज़ोन को सेकंड और नैनोसेकंड में बदलने के लिए, Timestamps.parse(String) जैसे यूटिलिटी फ़ंक्शन का इस्तेमाल किया जा सकता है.
ज़्यादा जानकारी के लिए, टाइमस्टैंप का फ़ॉर्मैट देखें. |
address |
user_data.user_identifiers[].address |
यह AddressInfo ऑब्जेक्ट से मैप होता है. पता ऑब्जेक्ट की मैपिंग देखें. |
gpp_string |
कोई मिलती-जुलती रिपोर्ट नहीं | सहमति को अनुरोध-लेवल या इवेंट-लेवल के Consent ऑब्जेक्ट पर मैप करें. निजता और सहमति की खास जानकारी देखें. |
gpp_sid |
कोई मिलती-जुलती रिपोर्ट नहीं | सहमति को अनुरोध-लेवल या इवेंट-लेवल के Consent ऑब्जेक्ट पर मैप करें. निजता और सहमति की खास जानकारी देखें. |
mmt_only |
कोई मिलती-जुलती रिपोर्ट नहीं | |
click_id |
ad_identifiers.gclid |
Google क्लिक आईडी (gclid) से मैप करें. ज़्यादा जानकारी के लिए, AdIdentifiers देखें. |
impression_id |
ad_identifiers.impression_id |
ज़्यादा जानकारी के लिए, AdIdentifiers पर जाएं. |
event_ip_address |
event_device_info.ip_address |
उपलब्ध फ़ील्ड के लिए, DeviceInfo देखें. |
event_user_agent |
event_device_info.user_agent |
उपलब्ध फ़ील्ड के लिए, DeviceInfo देखें. |
ifa |
ad_identifiers.mobile_device_id |
विज्ञापन देने वाले लोगों या कंपनियों के लिए मोबाइल आइडेंटिफ़ायर (iOS पर IDFA, Android पर विज्ञापन आईडी) से मैप करें. ज़्यादा जानकारी के लिए, AdIdentifiers पर जाएं. |
landing_ip_address |
ad_identifiers.landing_page_device_info.ip_address |
उपलब्ध फ़ील्ड के लिए, DeviceInfo देखें. |
landing_user_agent |
ad_identifiers.landing_page_device_info.user_agent |
उपलब्ध फ़ील्ड के लिए, DeviceInfo देखें. |
age_range |
कोई मिलती-जुलती रिपोर्ट नहीं | |
gender |
कोई मिलती-जुलती रिपोर्ट नहीं | |
ext |
कोई मिलती-जुलती रिपोर्ट नहीं |
पता ऑब्जेक्ट की मैपिंग
ECAPI (address) |
Data Manager API (AddressInfo) |
नोट |
|---|---|---|
first_name |
given_name |
AddressInfo में given_name फ़ील्ड से मैप करता है. फ़ॉर्मैटिंग और हैशिंग से जुड़े दिशा-निर्देशों का पालन करें. पते के हैश किए गए एट्रिब्यूट को एन्क्रिप्ट भी किया जा सकता है. |
last_name |
family_name |
AddressInfo में family_name फ़ील्ड से मैप करता है. फ़ॉर्मैटिंग और हैशिंग से जुड़े दिशा-निर्देशों का पालन करें. पते के हैश किए गए एट्रिब्यूट को एन्क्रिप्ट भी किया जा सकता है. |
street |
कोई मिलती-जुलती रिपोर्ट नहीं | डेटा मैनेजर एपीआई में काम नहीं करता. |
city |
कोई मिलती-जुलती रिपोर्ट नहीं | डेटा मैनेजर एपीआई में काम नहीं करता. |
state |
कोई मिलती-जुलती रिपोर्ट नहीं | डेटा मैनेजर एपीआई में काम नहीं करता. |
country_code |
region_code |
हैश न करें. AddressInfo में region_code फ़ील्ड से मैप करता है. फ़ॉर्मैटिंग से जुड़े दिशा-निर्देशों का पालन करें. |
postal_code |
postal_code |
हैश न करें. AddressInfo में postal_code फ़ील्ड से मैप करता है. फ़ॉर्मैटिंग से जुड़े दिशा-निर्देशों का पालन करें. |
address_type |
कोई मिलती-जुलती रिपोर्ट नहीं | डेटा मैनेजर एपीआई में काम नहीं करता. |
ext |
कोई मिलती-जुलती रिपोर्ट नहीं |
आइटम ऑब्जेक्ट की मैपिंग
ECAPI (item) |
Data Manager API (Item) |
नोट |
|---|---|---|
id |
item_id |
Google Analytics इवेंट के लिए ज़रूरी है. इसे आइटम के लिए स्टैंडर्ड और यूनीक आइडेंटिफ़ायर पर सेट करें. |
| कोई मिलती-जुलती रिपोर्ट नहीं | merchant_product_id |
Floodlight कन्वर्ज़न और कार्ट डेटा की मदद से Google Ads कन्वर्ज़न मेज़र करने की सुविधा के लिए ज़रूरी है. Merchant Center खाते में मौजूद प्रॉडक्ट आईडी पर सेट करें. |
name |
additional_item_parameters |
additional_item_parameters सूची में item_name के तौर पर मैप करें. |
price |
unit_price |
|
discount |
additional_item_parameters या custom_variables |
additional_item_parameters में discount के तौर पर (Google Analytics के लिए) या custom_variables में कस्टम वैरिएबल के तौर पर (Google Ads के लिए) मैप करें. |
quantity |
quantity |
float वैल्यू को पूर्णांक (int64) में बदलें. |
brand |
additional_item_parameters |
additional_item_parameters सूची में item_brand के तौर पर मैप करें. |
affiliation |
additional_item_parameters |
additional_item_parameters सूची में affiliation के तौर पर मैप करें. |
category |
additional_item_parameters |
additional_item_parameters सूची में item_category के तौर पर मैप करें. |
cattax |
कोई मिलती-जुलती रिपोर्ट नहीं | |
item_coupon |
additional_item_parameters |
additional_item_parameters सूची में coupon के तौर पर मैप करें. |
item_list_id |
additional_item_parameters |
additional_item_parameters सूची में item_list_id के तौर पर मैप करें. |
item_list_name |
additional_item_parameters |
additional_item_parameters सूची में item_list_name के तौर पर मैप करें. |
item_item_variant |
additional_item_parameters |
additional_item_parameters सूची में item_variant के तौर पर मैप करें. |
item_location_id |
additional_item_parameters |
additional_item_parameters में location_id के तौर पर मैप करें. |
ext |
कोई मिलती-जुलती रिपोर्ट नहीं |
स्टैंडर्ड इवेंट के नाम
ईसीएपीआई के स्टैंडर्ड इवेंट, Google Analytics के नाम रखने के तरीकों से काफ़ी मेल खाते हैं.
अगर Google Analytics डेटा स्ट्रीम में इवेंट भेजे जा रहे हैं, तो
event_nameफ़ील्ड भरना ज़रूरी है.हर इवेंट के लिए, उससे जुड़े फ़ील्ड, पैरामीटर, और Data Manager API में डेटा डालने के सैंपल अनुरोधों के बारे में जानने के लिए, Google Analytics में सुझाए गए इवेंट का रेफ़रंस देखें.
कस्टम इवेंट भी भेजे जा सकते हैं. हालांकि, इसके लिए ज़रूरी है कि वे इवेंट का नाम रखने के नियमों का पालन करते हों.
ज़्यादातर ECAPI स्टैंडर्ड इवेंट (जैसे कि purchase, add_to_cart, begin_checkout, search, और refund) का नाम, Google Analytics के सुझाए गए इवेंट के नाम जैसा ही होता है. हालांकि, कुछ मामलों में Google Analytics, पास्ट टेंस के बजाय प्रज़ेंट टेंस का इस्तेमाल करता है:
viewed_itemकोview_itemसे मैप किया गया हैviewed_item_listकोview_item_listसे मैप किया गया हैviewed_cartकोview_cartसे मैप किया गया है
अनुरोधों के उदाहरण
यहां दिए गए टैब में, ECAPI कन्वर्ज़न इवेंट पेलोड और मान्य Data Manager API IngestEventsRequest के तौर पर इसके प्रज़ेंटेशन के बीच तुलना दिखाई गई है:
ECAPI
यहां ईसीएपीआई की खास बातों के मुताबिक, JSON पेलोड का एक सैंपल दिया गया है:
{
"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
फ़ॉर्मैट, हैश, और कोड किए गए इवेंट डेटा के लिए, यहां IngestEventsRequest का एक सैंपल दिया गया है. डेस्टिनेशन में GOOGLE_ADS खाता टाइप से पता चलता है कि अनुरोध, Google Ads डेस्टिनेशन को टारगेट करता है:
{
"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
}
]
}
}
]
}