تخصیص مشخصات ECAPI

این راهنما به توسعه‌دهندگانی که از مشخصات 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
  • destinations[].product_destination_id (سطح درخواست)
  • destination_references (سطح رویداد)
 می‌توانید مقصدها را در سطوح زیر تعریف کنید:
  • سطح درخواست (الزامی): فهرست destinations را در IngestEventsRequest مشخص کنید.
  • سطح رویداد (اختیاری): از فیلد destination_references در شیء Event استفاده کنید. ورودی‌ای اضافه کنید تا مشخص شود کدام مقصد از فهرست destinations باید رویداد را دریافت کند.

برای اطلاعات بیشتر درباره نحوه تعریف Destination و تعیین شناسه مقصد محصول، به پیکربندی مقصدها و سرایندها مراجعه کنید.
id transaction_id رویدادهای تبدیل را تکرارزدایی می‌کند. نحوه مدیریت داده‌های چندمنبعی توسط Google را در راهنماهای ارسال رویداد برای Google Ads، Google Analytics، و Floodlight ببینید.
timestamp event_timestamp الزامی. ECAPI از قالب تاریخ یونیکس (عدد صحیح) برای مُهرهای زمان استفاده می‌کند. هنگام نگاشت به 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 تنظیم شده است.
properties
  • cart_data
  • custom_variables
  • additional_event_parameters
 موارد سطح تراکنش را به آرایه cart_data.items در شیء CartData نگاشت کنید. ‫Data Manager API از چندین فیلد Merchant Center اختیاری برای محصولاتی که در حساب‌های Merchant Center وجود دارند پشتیبانی می‌کند.

اگر مقصدتان کنش تبدیل Google Ads است، می‌توانید پارامترهای سفارشی اضافی را نیز در فیلد custom_variables به‌عنوان فهرستی از اشیاء CustomVariable اضافه کنید.

اگر مقصدتان جاری‌سازی داده Google Analytics است، می‌توانید پارامترهای رویداد بیشتری را در فیلد additional_event_parameters به‌عنوان فهرستی از اشیاء AdditionalEventParameter اضافه کنید.
ext بدون معادل

نگاشت شیء داده‌های کاربر

در Data Manager API، فیلد 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 بدون معادل ‫Data Manager API از آرایه ساختاریافته 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 بدون معادل در Data Manager API پشتیبانی نمی‌شود.
city بدون معادل در Data Manager API پشتیبانی نمی‌شود.
state بدون معادل در Data Manager API پشتیبانی نمی‌شود.
country_code region_code درهم‌سازی نکنید. به فیلد region_code در AddressInfo نگاشته می‌شود. دستورالعمل‌های قالب‌بندی را دنبال کنید.
postal_code postal_code درهم‌سازی نکنید. به فیلد postal_code در AddressInfo نگاشته می‌شود. دستورالعمل‌های قالب‌بندی را دنبال کنید.
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 نقشه به‌عنوان 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 هم‌راستا هستند.

اکثر رویدادهای استاندارد 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 مطابق با مشخصات 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
          }
        ]
      }
    }
  ]
}