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

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

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

ECAPI (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 पर IDFA, 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 कोई मिलती-जुलती रिपोर्ट नहीं

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

ECAPI (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 कोई मिलती-जुलती रिपोर्ट नहीं

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

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 (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
          }
        ]
      }
    }
  ]
}