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 कन्वर्ज़न इवेंट की डुप्लीकेट कॉपी हटाता है. Google Ads, Google Analytics, और Floodlight के लिए, इवेंट भेजने से जुड़ी गाइड में Google, अलग-अलग सोर्स से मिले डेटा को कैसे मैनेज करता है लेख पढ़ें.
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 कोई मिलती-जुलती रिपोर्ट नहीं 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 पर 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 कोई मिलती-जुलती रिपोर्ट नहीं डेटा मैनेजर एपीआई में इसका इस्तेमाल नहीं किया जा सकता.
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 (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 maps to view_cart

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

यहां दिए गए टैब में, ECAPI कन्वर्ज़न इवेंट पेलोड और मान्य 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
          }
        ]
      }
    }
  ]
}