ECAPI स्पेसिफ़िकेशन मैपिंग

इस गाइड से, 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 के स्वीकार किए गए फ़ील्ड में कैसे ट्रांसलेट होते हैं.

इवेंट ऑब्जेक्ट मैपिंग

ईसीएपीआई (event) Data Manager API (Event) नोट
data_set_id
  • destinations[].product_destination_id (अनुरोध का लेवल)
  • destination_references (इवेंट लेवल)
 इसे इन लेवल पर तय किया जा सकता है:
  • अनुरोध लेवल (ज़रूरी है): IngestEventsRequest में destinations की सूची दें.
  • इवेंट लेवल: Event ऑब्जेक्ट पर मौजूद destination_references फ़ील्ड का इस्तेमाल करें. एक एंट्री जोड़कर यह तय करें कि destinations सूची में से किस डेस्टिनेशन को इवेंट मिलेगा.

Destination को तय करने और प्रॉडक्ट डेस्टिनेशन आईडी का पता लगाने के तरीके के बारे में ज़्यादा जानने के लिए, डेस्टिनेशन और हेडर कॉन्फ़िगर करना लेख पढ़ें.
id transaction_id इस वैल्यू का इस्तेमाल, कन्वर्ज़न इवेंट को डुप्लीकेट होने से रोकने के लिए किया जाता है. ज़्यादा जानें.
timestamp event_timestamp ज़रूरी है. ECAPI, टाइमस्टैंप के लिए Unix epoch फ़ॉर्मैट (पूर्णांक) का इस्तेमाल करता है. Data Manager API पर मैप करते समय, event_timestamp फ़ील्ड को इनमें से किसी एक फ़ॉर्मैट में बदलना होगा:
  • अगर JSON फ़ॉर्मैट का इस्तेमाल किया जा रहा है, तो इसे RFC 3339 फ़ॉर्मैट में सेट करें.
  • प्रोटोकॉल बफ़र का इस्तेमाल करते समय, Timestamp का इस्तेमाल करें. साथ ही, seconds और (ज़रूरी नहीं) nanoseconds फ़ील्ड सेट करें.

ज़्यादा जानकारी के लिए, टाइमस्टैंप का फ़ॉर्मैट देखें.
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
  • cart_data
  • custom_variables
  • additional_event_parameters
 लेन-देन के लेवल के आइटम को 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 ऑब्जेक्ट की सूची की ज़रूरत होती है. इसमें ईमेल पते, फ़ोन नंबर या पते के कॉम्पोनेंट जैसे उपयोगकर्ता के अलग-अलग आइडेंटिफ़ायर शामिल हो सकते हैं.

ईसीएपीआई (user_data) Data Manager API (Event) नोट
customer_identifier user_id (Google Analytics) Google Analytics इवेंट के लिए, user_id फ़ील्ड, User-ID को दिखाता है. Data Manager API, अन्य डेस्टिनेशन के लिए सामान्य ग्राहक आईडी फ़ील्ड का इस्तेमाल नहीं करता.
uids कोई मिलती-जुलती रिपोर्ट नहीं डेटा मैनेजर एपीआई, एजेंट टाइप और डोमेन की जानकारी देने वाले स्ट्रक्चर्ड 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 पर आईडीएफ़ए, Android पर AdID) पर मैप करें. ज़्यादा जानकारी के लिए, 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 कोई मिलती-जुलती रिपोर्ट नहीं

पता ऑब्जेक्ट मैपिंग

ईसीएपीआई (address) Data Manager API (AddressInfo) नोट
first_name given_name यह AddressInfo में मौजूद given_name फ़ील्ड से मैप होता है. फ़ॉर्मैटिंग और हैशिंग के दिशा-निर्देशों का पालन करें. पते के हैश किए गए एट्रिब्यूट को भी एन्क्रिप्ट (सुरक्षित) किया जा सकता है.
last_name family_name यह AddressInfo में मौजूद family_name फ़ील्ड से मैप होता है. फ़ॉर्मैटिंग और हैशिंग के दिशा-निर्देशों का पालन करें. पते के हैश किए गए एट्रिब्यूट को भी एन्क्रिप्ट (सुरक्षित) किया जा सकता है.
street कोई मिलती-जुलती रिपोर्ट नहीं Data Manager API में मौजूद नहीं है
city कोई मिलती-जुलती रिपोर्ट नहीं Data Manager API में मौजूद नहीं है
state कोई मिलती-जुलती रिपोर्ट नहीं Data Manager API में मौजूद नहीं है
country_code region_code हैश न करें. यह AddressInfo में मौजूद region_code फ़ील्ड से मैप होता है. फ़ॉर्मैटिंग से जुड़े दिशा-निर्देशों का पालन करें.
postal_code postal_code हैश न करें. यह AddressInfo में मौजूद postal_code फ़ील्ड से मैप होता है. फ़ॉर्मैटिंग से जुड़े दिशा-निर्देशों का पालन करें.
address_type कोई मिलती-जुलती रिपोर्ट नहीं Data Manager API में मौजूद नहीं है
ext कोई मिलती-जुलती रिपोर्ट नहीं

आइटम ऑब्जेक्ट मैपिंग

ईसीएपीआई (item) Data Manager API (Item) नोट
id item_id Google Analytics इवेंट के लिए ज़रूरी है. इसे आइटम के लिए स्टैंडर्ड यूनीक आइडेंटिफ़ायर पर सेट किया जाता है.
कोई मिलती-जुलती रिपोर्ट नहीं merchant_product_id कार्ट डेटा के साथ Google Ads कन्वर्ज़न और Floodlight कन्वर्ज़न के लिए ज़रूरी है. इसे Merchant Center खाते में मौजूद प्रॉडक्ट आईडी पर सेट किया जाता है.
name additional_item_parameters additional_item_parameters सूची में item_name के तौर पर मैप करें.
price unit_price
discount additional_item_parameters या custom_variables additional_item_parameters (Google Analytics के लिए) में discount के तौर पर या 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 कोई मिलती-जुलती रिपोर्ट नहीं

स्टैंडर्ड इवेंट के नाम

ECAPI के स्टैंडर्ड इवेंट, 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 तक

अनुरोध के उदाहरण

नीचे दिए गए टैब में, ईसीएपीआई कन्वर्ज़न इवेंट के पेलोड और Data Manager API IngestEventsRequest के तौर पर उसके मान्य वर्शन की तुलना दिखाई गई है.

ECAPI

यहां 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
          }
        ]
      }
    }
  ]
}