تخصیص مشخصات 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 Ads، Google Analytics، و Floodlight، ببینید Google چگونه داده‌های چند منبعی را مدیریت می‌کند.
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 نگاشت کنید. «میانای برنامه‌سازی کاربردی مدیر داده» از چندین فیلد اختیاری 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 هم‌راستا هستند.

بیشتر رویدادهای استاندارد 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
          }
        ]
      }
    }
  ]
}