این راهنما به توسعهدهندگانی که از مشخصات IAB Tech Lab Event and Conversion API (ECAPI) استفاده میکنند کمک میکند دادههای رویداد و تبدیل خود را به طرحواره دریافت رویداد Data Manager API تخصیص دهند.
نمای کلی
ECAPI یک استاندارد داده متنباز و مستقل از پلاتفرم است که ساختار رویدادها و تبدیلهای مرتبط با بازاریابی را تعریف میکند.
جدول زیر نمایی کلی از نحوه مقایسه ویژگیهای کلیدی و اصول طراحی ECAPI با Data Manager API ارائه میدهد:
| ECAPI | میانای برنامهسازی کاربردی مدیر دادهها | |
|---|---|---|
| حذف موارد تکراری | به id (شناسه رویداد) متکی است |
به transaction_id متکی است |
| مسیریابی رویداد | فیلد data_set_id در بار داده رویداد نشاندهنده مقصد دادهها است. |
فیلد destinations درخواست، مقصد رویدادها را تعریف میکند.
Data Manager API همچنین از مسیریابی رویدادها به چند مقصد در یک درخواست پشتیبانی میکند. برای اطلاعات بیشتر، پیکربندی مقصدها و سرصفحهها را ببینید. |
| فیلدهای حریم خصوصی و رضایت | رشتههای موافقت «پلاتفرم حریم خصوصی جهانی» (GPP) |
Data Manager API رشتههای رضایت «پلاتفرم حریم خصوصی جهانی» (GPP) را نمیپذیرد یا تجزیه نمیکند. فیلدهای رضایت را در شیء Consent تنظیم کنید.
میتوانید رضایت را در سطح درخواست (که برای همه رویدادها در درخواست اعمال میشود) یا در سطح رویداد (که به شما امکان میدهد تنظیمات رضایت متفاوتی را برای رویدادهای تکی مشخص کنید) تنظیم کنید. |
نگاشت فیلد ساختاری
جدولهای نگاشت زیر تعریف میکنند که چگونه فیلدهای منفرد از مشخصات ECAPI به فیلدهای پذیرفتهشده توسط Data Manager API ترجمه میشوند:
تخصیص دادن شیء رویداد
ECAPI (event) |
Data Manager API (Event) |
یادداشتها |
|---|---|---|
data_set_id |
|
میتوانید مقصدها را در سطوح زیر تعریف کنید:
برای اطلاعات بیشتر درباره نحوه تعریف Destination
و تعیین شناسه مقصد محصول، به
پیکربندی مقصدها و سرایندها مراجعه کنید.
|
id |
transaction_id |
رویدادهای تبدیل را تکرارزدایی میکند. در راهنمای ارسال رویدادها برای Google Ads، Google Analytics، و Floodlight، ببینید Google چگونه دادههای چند منبعی را مدیریت میکند. |
timestamp |
event_timestamp |
الزامی. ECAPI از قالب تاریخ یونیکس (عدد صحیح) برای مُهرهای زمان استفاده میکند.
هنگام نگاشت به Data Manager API، فیلد event_timestamp را به یکی از قالبهای زیر تبدیل کنید:
برای جزئیات، قالب مُهر زمان را ببینید. |
event_type / custom_event |
event_name |
این نام میتواند نام رویداد توصیهشده (برای مثال، purchase) یا نام رویداد سفارشی باشد. برای جزئیات، به نامهای رویداد استاندارد مراجعه کنید. |
user_data |
user_data |
به شیء UserData که فهرست اشیا UserIdentifier را میپذیرد نگاشت میشود. |
value |
conversion_value |
مستقیماً بهعنوان عدد اعشاری یا شناور نشاندهنده مقدار پولی تبدیل نقشه کنید. |
currency_code |
currency |
به کد ارز سهحرفی با حروف بزرگ (برای مثال، USD) نگاشت کنید. |
source |
event_source |
روی مقداری از شمارش EventSource تنظیم کنید. |
properties |
|
موارد سطح تراکنش را به آرایه cart_data.items در شیء CartData نگاشت کنید. «میانای برنامهسازی کاربردی مدیر داده» از چندین فیلد اختیاری Merchant Center برای محصولات
موجود در حسابهای Merchant Center پشتیبانی میکند.
اگر مقصدتان کنش تبدیل Google Ads است، میتوانید پارامترهای سفارشی اضافی را نیز در فیلد custom_variables بهعنوان فهرستی از اشیاء CustomVariable اضافه کنید.
اگر مقصدتان جاریسازی داده Google Analytics است، میتوانید پارامترهای رویداد اضافی را در فیلد additional_event_parameters بهصورت فهرستی از
AdditionalEventParameter اشیا اضافه کنید.
|
ext |
معادل ندارد |
نگاشت شیء دادههای کاربر
در «میانای برنامهسازی کاربردی مدیر دادهها»، فیلد user_data در شیء Event
شیء UserData را میپذیرد. این مورد انتظار فهرستی از اشیاء
UserIdentifier را دارد که میتواند حاوی شناسههای کاربری فردی مانند نشانیهای ایمیل، شماره تلفن، یا مؤلفههای نشانی باشد:
ECAPI (user_data) |
Data Manager API (Event) |
یادداشتها |
|---|---|---|
customer_identifier |
user_id (Google Analytics) |
برای رویدادهای Google Analytics، فیلد user_id نشاندهنده شناسه کاربر است. Data Manager API از فیلدهای شناسه مشتری عمومی برای مقصدهای دیگر پشتیبانی نمیکند. |
uids |
معادل ندارد | «میانای برنامهسازی کاربردی مدیر داده» از آرایه ساختاریافته uids حاوی انواع و دامنههای کارگزار پشتیبانی نمیکند. |
customer_segments |
user_properties |
نقشه UserProperties در Event. |
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 |
به شناسه تلفن همراه برای تبلیغکنندگان (IDFA در iOS، AdID در Android) نگاشت کنید. برای جزئیات بیشتر، به 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 |
به فیلد given_name در AddressInfo نگاشت میشود. دستورالعملهای قالببندی و درهمسازی را دنبال کنید. همچنین میتوانید مشخصههای درهمسازیشده نشانی را رمزگذاری کنید. |
last_name |
family_name |
به فیلد family_name در AddressInfo نگاشته میشود. دستورالعملهای قالببندی و درهمسازی را دنبال کنید. همچنین میتوانید مشخصههای درهمسازیشده نشانی را رمزگذاری کنید. |
street |
بدون معادل | در «میانای برنامهسازی کاربردی مدیر داده» پشتیبانی نمیشود. |
city |
معادل ندارد | در «میانای برنامهسازی کاربردی مدیر داده» پشتیبانی نمیشود. |
state |
معادل ندارد | در Data Manager API پشتیبانی نمیشود. |
country_code |
region_code |
درهمسازی نکنید. به فیلد region_code در AddressInfo نگاشت میشود. دستورالعملهای قالببندی را دنبال کنید. |
postal_code |
postal_code |
درهمسازی نکنید. به فیلد postal_code در AddressInfo نگاشت میشود. دستورالعملهای قالببندی را دنبال کنید. |
address_type |
معادل ندارد | در «میانای برنامهسازی کاربردی مدیر داده» پشتیبانی نمیشود. |
ext |
بدون معادل |
نگاشت شیء مورد
ECAPI (item) |
میانای برنامهسازی کاربردی مدیر دادهها (Item) |
یادداشتها |
|---|---|---|
id |
item_id |
برای رویدادهای Google Analytics الزامی است. روی شناسه استاندارد و یکتایی برای مورد تنظیم شده است. |
| معادل ندارد | merchant_product_id |
برای تبدیلهای Floodlight و تبدیلهای Google Ads با دادههای سبد خرید الزامی است. روی شناسه محصول در حساب Merchant Center تنظیم شده است. |
name |
additional_item_parameters |
نقشه بهعنوان item_name در فهرست additional_item_parameters. |
price |
unit_price |
|
discount |
additional_item_parameters یا custom_variables |
بهعنوان discount در additional_item_parameters (برای Google Analytics) یا بهعنوان متغیر سفارشی در custom_variables (برای Google Ads) نگاشت کنید. |
quantity |
quantity |
مقدار float را به عدد صحیح (int64) تبدیل کنید. |
brand |
additional_item_parameters |
نقشه بهعنوان item_brand در فهرست additional_item_parameters. |
affiliation |
additional_item_parameters |
نقشه بهعنوان affiliation در فهرست additional_item_parameters. |
category |
additional_item_parameters |
نقشه بهعنوان item_category در فهرست additional_item_parameters. |
cattax |
بدون معادل | |
item_coupon |
additional_item_parameters |
نقشه بهعنوان coupon در فهرست additional_item_parameters. |
item_list_id |
additional_item_parameters |
item_list_id را در فهرست additional_item_parameters نقشهبندی کنید. |
item_list_name |
additional_item_parameters |
item_list_name را در فهرست additional_item_parameters نقشهبندی کنید. |
item_item_variant |
additional_item_parameters |
نقشه بهعنوان item_variant در فهرست additional_item_parameters. |
item_location_id |
additional_item_parameters |
نقشه بهعنوان location_id در additional_item_parameters. |
ext |
معادل ندارد |
نامهای رویداد استاندارد
رویدادهای استاندارد ECAPI بهشدت با قراردادهای نامگذاری Google Analytics همراستا هستند.
اگر رویدادها را به جریان داده Google Analytics ارسال میکنید، فیلد
event_nameالزامی است.برای اطلاع از فیلدها، پارامترها، و نمونه درخواستهای جذب Data Manager API برای هر رویداد، مرجع رویدادهای توصیهشده 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
و نمایش آن بهعنوان «میانای برنامهسازی کاربردی مدیر داده» معتبر
IngestEventsRequest را نشان میدهد:
ECAPI
در اینجا نمونهای از پایهبار JSON مطابق با مشخصات ECAPI آورده شده است:
{
"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 در مقصد نشان میدهد که درخواست مقصد 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
}
]
}
}
]
}