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

এই নির্দেশিকাটি IAB টেক ল্যাব ইভেন্ট অ্যান্ড কনভার্সন এপিআই (ECAPI) স্পেসিফিকেশন ব্যবহারকারী ডেভেলপারদের তাদের ইভেন্ট এবং কনভার্সন ডেটাকে ডেটা ম্যানেজার এপিআই ইভেন্ট ইনজেশন স্কিমার সাথে ম্যাপ করতে সাহায্য করে।

সংক্ষিপ্ত বিবরণ

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

নিম্নলিখিত সারণিটি ECAPI-এর মূল বৈশিষ্ট্য এবং নকশার নীতিগুলির সাথে ডেটা ম্যানেজার API-এর তুলনা করে একটি সামগ্রিক ধারণা প্রদান করে।

	ECAPI	ডেটা ম্যানেজার এপিআই
ডুপ্লিকেট অপসারণ	id (ইভেন্ট আইডি)-র উপর নির্ভর করে	transaction_id উপর নির্ভর করে
ইভেন্ট রাউটিং	ইভেন্ট পেলোডের data_set_id ফিল্ড দ্বারা ডেটার গন্তব্য নির্দেশিত হয়।	অনুরোধের ' destinations ' ক্ষেত্রটি ইভেন্টগুলির গন্তব্যস্থল নির্ধারণ করে। ডেটা ম্যানেজার এপিআই একটিমাত্র অনুরোধে একাধিক গন্তব্যে ইভেন্ট রাউটিং করাও সমর্থন করে। আরও তথ্যের জন্য গন্তব্যস্থল নির্দেশিকা দেখুন।
গোপনীয়তা এবং সম্মতি ক্ষেত্র	গ্লোবাল প্রাইভেসি প্ল্যাটফর্ম (GPP) সম্মতি স্ট্রিং	ডেটা ম্যানেজার এপিআই গ্লোবাল প্রাইভেসি প্ল্যাটফর্ম (জিপিপি)-এর সম্মতি স্ট্রিং গ্রহণ বা পার্স করে না। সম্মতির ফিল্ডগুলো অবশ্যই Consent অবজেক্টে সেট করতে হবে। আপনি অনুরোধ স্তরে (যা অনুরোধের সমস্ত ইভেন্টের জন্য প্রযোজ্য) অথবা ইভেন্ট স্তরে (যা আপনাকে স্বতন্ত্র ইভেন্টের জন্য ভিন্ন ভিন্ন সম্মতি সেটিংস নির্দিষ্ট করার সুযোগ দেয়) সম্মতি নির্ধারণ করতে পারেন।

কাঠামোগত ক্ষেত্র ম্যাপিং

নিম্নলিখিত ম্যাপিং টেবিলগুলো সংজ্ঞায়িত করে যে, ECAPI স্পেসিফিকেশনের স্বতন্ত্র ফিল্ডগুলো কীভাবে ডেটা ম্যানেজার এপিআই দ্বারা গৃহীত ফিল্ডে রূপান্তরিত হয়।

পরামর্শ: ইভেন্ট পাঠানো শুরু করতে এবং প্রতিটি ইভেন্ট ইনজেশন ব্যবহারের ক্ষেত্রের জন্য প্রয়োজনীয় ও ঐচ্ছিক ফিল্ডগুলো সম্পর্কে আরও জানতে ‘ইভেন্ট পাঠান’ নির্দেশিকাটি দেখুন।

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

ECAPI ( event )	ডেটা ম্যানেজার এপিআই ( Event )	নোট
data_set_id	destinations[].product_destination_id (অনুরোধ স্তর) destination_references (ইভেন্ট স্তর)	নিম্নলিখিত স্তরগুলিতে সংজ্ঞায়িত করা যেতে পারে: অনুরোধের স্তর (আবশ্যক) : IngestEventsRequest এ destinations তালিকা উল্লেখ করুন। ইভেন্ট লেভেল: Event অবজেক্টের destination_references ফিল্ডটি ব্যবহার করুন। destinations তালিকা থেকে কোন ডেস্টিনেশনে ইভেন্টটি পাঠানো হবে, তা নির্দিষ্ট করতে একটি এন্ট্রি যোগ করুন। কিভাবে একটি Destination নির্ধারণ করতে হয় এবং পণ্যের গন্তব্য আইডি নির্ণয় করতে হয়, সে সম্পর্কে আরও তথ্যের জন্য, ‘গন্তব্য এবং হেডার কনফিগার করুন’ দেখুন।
id	transaction_id	এই মানটি রূপান্তর ইভেন্টগুলির পুনরাবৃত্তি দূর করতে ব্যবহৃত হয়। আরও জানুন ।
timestamp	event_timestamp	আবশ্যক। ECAPI টাইমস্ট্যাম্পের জন্য ইউনিক্স ইপক ফরম্যাট (পূর্ণসংখ্যা) ব্যবহার করে। ডেটা ম্যানেজার এপিআই-তে ম্যাপিং করার সময়, 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 অ্যারেতে ম্যাপ করা যায়। ডেটা ম্যানেজার এপিআই, মার্চেন্ট সেন্টার অ্যাকাউন্টে বিদ্যমান প্রোডাক্টগুলোর জন্য বেশ কিছু ঐচ্ছিক মার্চেন্ট সেন্টার ফিল্ড সমর্থন করে। আপনার গন্তব্য যদি কোনো গুগল অ্যাডস কনভার্সন অ্যাকশন হয়, তাহলে আপনি custom_variables ফিল্ডে CustomVariable অবজেক্টের একটি তালিকা হিসেবে অতিরিক্ত কাস্টম প্যারামিটারও অন্তর্ভুক্ত করতে পারেন। আপনার গন্তব্য যদি একটি গুগল অ্যানালিটিক্স ডেটা স্ট্রিম হয়, তাহলে আপনি additional_event_parameters ফিল্ডে AdditionalEventParameter অবজেক্টের একটি তালিকা হিসেবে অতিরিক্ত ইভেন্ট প্যারামিটার অন্তর্ভুক্ত করতে পারেন।
ext	কোনো সমতুল্য নেই

ব্যবহারকারীর ডেটা অবজেক্ট ম্যাপিং

পরামর্শ: প্রতিটি গন্তব্য এবং ব্যবহারের ক্ষেত্রের জন্য কোন শনাক্তকারীগুলো প্রয়োজনীয় ও সুপারিশকৃত, সে সম্পর্কে আরও তথ্যের জন্য ‘ইভেন্ট পাঠান’ নির্দেশিকার ‘ ডেটাকে Event অবজেক্টে রূপান্তর করুন’ অংশটি দেখুন।

ডেটা ম্যানেজার এপিআই-তে, Event অবজেক্টের user_data ফিল্ডটি একটি UserData অবজেক্ট গ্রহণ করে। এটি UserIdentifier অবজেক্টের একটি তালিকা আশা করে, যেটিতে স্বতন্ত্র ব্যবহারকারী শনাক্তকারী যেমন ইমেল ঠিকানা, ফোন নম্বর বা ঠিকানার উপাদান থাকতে পারে।

ECAPI ( user_data )	ডেটা ম্যানেজার এপিআই ( Event )	নোট
customer_identifier	user_id (গুগল অ্যানালিটিক্স)	গুগল অ্যানালিটিক্স ইভেন্টের ক্ষেত্রে, user_id ফিল্ডটি একটি ইউজার-আইডি নির্দেশ করে। ডেটা ম্যানেজার এপিআই অন্যান্য গন্তব্যের জন্য জেনেরিক কাস্টমার আইডি ফিল্ড সমর্থন করে না।
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 অবজেক্টের সাথে ম্যাপ করা হয়। Address অবজেক্ট ম্যাপিং দেখুন।
gpp_string	কোনো সমতুল্য নেই	সম্মতি অবশ্যই অনুরোধ-স্তরের বা ইভেন্ট-স্তরের Consent অবজেক্টের সাথে ম্যাপ করতে হবে। গোপনীয়তা এবং সম্মতি ওভারভিউ দেখুন।
gpp_sid	কোনো সমতুল্য নেই	সম্মতি অবশ্যই অনুরোধ-স্তরের বা ইভেন্ট-স্তরের Consent অবজেক্টের সাথে ম্যাপ করতে হবে। গোপনীয়তা এবং সম্মতি ওভারভিউ দেখুন।
mmt_only	কোনো সমতুল্য নেই
click_id	ad_identifiers.gclid	গুগল ক্লিক আইডি ( 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 )	ডেটা ম্যানেজার এপিআই ( 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 )	ডেটা ম্যানেজার এপিআই ( Item )	নোট
id	item_id	গুগল অ্যানালিটিক্স ইভেন্টের জন্য এটি আবশ্যক । আইটেমটির জন্য একটি প্রমিত, অনন্য শনাক্তকারীতে সেট করুন।
কোনো সমতুল্য নেই	merchant_product_id	ফ্ল্যাডলাইট কনভার্সন এবং কার্ট ডেটা সহ গুগল অ্যাডস কনভার্সনের জন্য এটি আবশ্যক । মার্চেন্ট সেন্টার অ্যাকাউন্টের মধ্যে প্রোডাক্ট আইডিতে এটি সেট করতে হবে।
name	additional_item_parameters	additional_item_parameters তালিকায় item_name হিসেবে ম্যাপ করুন।
price	unit_price
discount	additional_item_parameters বা custom_variables	গুগল অ্যানালিটিক্স-এর জন্য additional_item_parameters এ discount হিসেবে অথবা গুগল অ্যাডস-এর জন্য custom_variables এ একটি কাস্টম ভেরিয়েবল হিসেবে ম্যাপ করুন।
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 স্ট্যান্ডার্ড ইভেন্টগুলো গুগল অ্যানালিটিক্স-এর নামকরণের রীতির সাথে ব্যাপকভাবে সামঞ্জস্যপূর্ণ।

• আপনি যদি গুগল অ্যানালিটিক্স ডেটা স্ট্রিমে ইভেন্ট পাঠান, তাহলে event_name ফিল্ডটি আবশ্যক ।
• প্রতিটি ইভেন্টের সাথে সম্পর্কিত ফিল্ড, প্যারামিটার এবং নমুনা ডেটা ম্যানেজার এপিআই ইনজেশন রিকোয়েস্ট জানতে গুগল অ্যানালিটিক্স-এর প্রস্তাবিত ইভেন্ট রেফারেন্সটি দেখুন।
• আপনি কাস্টম ইভেন্টও পাঠাতে পারেন, তবে শর্ত হলো সেগুলো ইভেন্টের নামকরণের নিয়ম মেনে চলতে হবে।

বেশিরভাগ 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
      }
    ]
  }
}

ডেটা ম্যানেজার এপিআই

এখানে ফরম্যাট করা, হ্যাশ করা এবং এনকোড করা ইভেন্ট ডেটার জন্য একটি নমুনা IngestEventsRequest দেওয়া হলো। এটি একটি গুগল অ্যাডস ডেস্টিনেশনের জন্য, যা ডেস্টিনেশনে থাকা 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
          }
        ]
      }
    }
  ]
}