ECAPI স্পেসিফিকেশন ম্যাপিং

এই নির্দেশিকা IAB Tech Lab Event and Conversion API (ECAPI) স্পেসিফিকেশন ব্যবহার করা ডেভেলপারদের তাদের ইভেন্ট এবং কনভার্সন ডেটা Data Manager API ইভেন্ট ইনজেশন স্কিমা-তে ম্যাপ করতে সাহায্য করে।

এক নজরে

ECAPI হল একটি প্ল্যাটফর্ম-অ্যাগনস্টিক, ওপেন-সোর্স ডেটা স্ট্যান্ডার্ড যা মার্কেটিং-সম্পর্কিত ইভেন্ট এবং কনভার্সনের কাঠামোকে সংজ্ঞায়িত করে।

নিম্নলিখিত সারণীতে ECAPI-এর মূল অ্যাট্রিবিউট ও ডিজাইন নীতি কীভাবে ডেটা ম্যানেজার API-এর সাথে তুলনা করা হয় তার একটি উচ্চ-স্তরের ভিউ প্রদান করে:

ECAPI Data Manager API
ডুপ্লিকেট ডেটা সরানো id-এর (ইভেন্ট আইডি) উপর নির্ভর করে transaction_id-এর উপর নির্ভর করে
ইভেন্ট রাউটিং ইভেন্ট পেলোডের data_set_id ফিল্ড ডেটার গন্তব্য নির্দেশ করে। অনুরোধের destinations ফিল্ড ইভেন্টের জন্য গন্তব্য নির্ধারণ করে।

এছাড়াও, Data Manager API একটি অনুরোধে একাধিক গন্তব্যে ইভেন্ট রাউটিং করার সুবিধা দেয়।

আরও তথ্যের জন্য গন্তব্য ও হেডার কনফিগার করুন দেখুন।
গোপনীয়তা ও সম্মতি সংক্রান্ত ফিল্ড গ্লোবাল প্রাইভেসি প্ল্যাটফর্ম (GPP) সম্মতি স্ট্রিং ডেটা ম্যানেজার API, গ্লোবাল প্রাইভেসি প্ল্যাটফর্ম (GPP) সম্মতি স্ট্রিং গ্রহণ বা পার্স করে না। Consent অবজেক্টে সম্মতি ফিল্ড সেট করুন।

আপনি অনুরোধ লেভেলে (যা অনুরোধের সব ইভেন্টের ক্ষেত্রে প্রযোজ্য) অথবা ইভেন্ট লেভেলে (যা আপনাকে আলাদা আলাদা ইভেন্টের জন্য আলাদা আলাদা সম্মতি সেটিংস নির্দিষ্ট করতে দেয়) সম্মতি সেট করতে পারেন।

স্ট্রাকচারাল ফিল্ড ম্যাপিং

নিম্নলিখিত ম্যাপিং টেবিল থেকে বোঝা যায় যে ECAPI স্পেসিফিকেশন থেকে স্বতন্ত্র ফিল্ডগুলি কীভাবে ডেটা ম্যানেজার API দ্বারা গৃহীত ফিল্ডে অনুবাদ করা হয়:

ইভেন্ট অবজেক্ট ম্যাপিং

ECAPI (event) Data Manager API (Event) নোট
data_set_id
  • destinations[].product_destination_id (অনুরোধের লেভেল)
  • destination_references (ইভেন্ট লেভেল)
 আপনি নিম্নলিখিত লেভেলে গন্তব্য নির্ধারণ করতে পারবেন:
  • অনুরোধ লেভেল (প্রয়োজনীয়): destinations-এর তালিকা IngestEventsRequest-এ উল্লেখ করুন।
  • ইভেন্ট লেভেল (ঐচ্ছিক): Event অবজেক্টে destination_references ফিল্ড ব্যবহার করুন। destinations তালিকা থেকে কোন গন্তব্য ইভেন্টটি পাবে তা নির্দিষ্ট করতে একটি এন্ট্রি যোগ করুন।

কীভাবে Destination নির্ধারণ করবেন এবং প্রোডাক্ট ডেস্টিনেশন আইডি ঠিক করবেন সেই সম্পর্কে আরও জানতে, ডেস্টিনেশন ও হেডার কনফিগার করুন দেখুন।
id transaction_id কনভার্সন ইভেন্ট ডিডুপ্লিকেট করে। Google Ads, Google Analytics ও Floodlight-এর জন্য ইভেন্ট পাঠান সংক্রান্ত গাইডে Google কীভাবে মাল্টি-সোর্স ডেটা ম্যানেজ করে তা দেখুন।
timestamp event_timestamp প্রয়োজনীয়। ECAPI টাইমস্ট্যাম্পের জন্য Unix epoch ফর্ম্যাট (পূর্ণসংখ্যা) ব্যবহার করে। ডেটা ম্যানেজার 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 অ্যারের সাথে ম্যাপ করুন। Merchant Center অ্যাকাউন্টে থাকা প্রোডাক্টের জন্য Data Manager API-তে একাধিক ঐচ্ছিক 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) ডেটা ম্যানেজার 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-এ 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) ডেটা ম্যানেজার API (AddressInfo) নোট
first_name given_name AddressInfo-এ given_name ফিল্ডের ম্যাপ। ফর্ম্যাটিং ও হ্যাশিং সংক্রান্ত নির্দেশিকা অনুসরণ করুন। এছাড়াও, আপনি ঠিকানার হ্যাশ করা অ্যাট্রিবিউট এনক্রিপ্ট করতে পারবেন।
last_name family_name AddressInfo-এ family_name ফিল্ডের ম্যাপ। ফর্ম্যাটিং ও হ্যাশিং সংক্রান্ত নির্দেশিকা মেনে চলুন। এছাড়াও, আপনি ঠিকানার হ্যাশ করা অ্যাট্রিবিউট এনক্রিপ্ট করতে পারবেন।
street সমতুল্য কিছু নেই ডেটা ম্যানেজার API-তে কাজ করে না।
city সমতুল্য কিছু নেই ডেটা ম্যানেজার API-তে কাজ করে না।
state সমতুল্য কিছু নেই ডেটা ম্যানেজার API-তে কাজ করে না।
country_code region_code হ্যাশ করবেন না। AddressInfo-এ region_code ফিল্ডে ম্যাপ করে। ফর্ম্যাটিং সংক্রান্ত নির্দেশিকা অনুসরণ করুন।
postal_code postal_code হ্যাশ করবেন না। AddressInfo-এ postal_code ফিল্ডে ম্যাপ করে। ফর্ম্যাটিং সংক্রান্ত নির্দেশিকা অনুসরণ করুন।
address_type সমতুল্য কিছু নেই ডেটা ম্যানেজার 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 কনভার্সন ইভেন্ট পেলোড এবং সঠিক ডেটা ম্যানেজার 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
          }
        ]
      }
    }
  ]
}