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 कन्वर्ज़न इवेंट की डुप्लीकेट कॉपी हटाता है. 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 कोई मिलती-जुलती रिपोर्ट नहीं

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

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

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

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 से मैप किया गया है

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

यहां दिए गए टैब में, 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
          }
        ]
      }
    }
  ]
}