این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

نگاشت مشخصات ECAPI

این راهنما به توسعه‌دهندگانی که از مشخصات API رویداد و تبدیل (ECAPI) آزمایشگاه فناوری IAB استفاده می‌کنند، کمک می‌کند تا داده‌های رویداد و تبدیل خود را به طرحواره دریافت رویداد API مدیر داده نگاشت کنند .

نمای کلی

ECAPI یک استاندارد داده متن‌باز و مستقل از پلتفرم است که برای تعریف نحوه ساختاردهی رویدادها و تبدیل‌های مرتبط با بازاریابی طراحی شده است.

جدول زیر نمای سطح بالایی از چگونگی مقایسه ویژگی‌های کلیدی و اصول طراحی ECAPI با رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API) ارائه می‌دهد.

	ایکاپی	رابط برنامه‌نویسی کاربردی مدیریت داده
حذف داده‌های تکراری	متکی بر `id` (شناسه رویداد)	به `transaction_id` متکی است
مسیریابی رویداد	مقصد داده‌ها توسط فیلد `data_set_id` در payload رویداد مشخص می‌شود.	فیلد `destinations` درخواست، مقصد(های) رویدادها را تعریف می‌کند. رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API) همچنین از مسیریابی رویدادها به چندین مقصد در یک درخواست واحد پشتیبانی می‌کند. برای اطلاعات بیشتر به راهنمای مقصد مراجعه کنید.
فیلدهای حریم خصوصی و رضایت	رشته‌های رضایت پلتفرم جهانی حریم خصوصی (GPP)	رابط برنامه‌نویسی کاربردی مدیریت داده، رشته‌های رضایت پلتفرم جهانی حریم خصوصی (GPP) را نمی‌پذیرد یا تجزیه نمی‌کند. فیلدهای رضایت باید در شیء `Consent` تنظیم شوند. شما می‌توانید رضایت را در سطح درخواست (که برای همه رویدادهای موجود در درخواست اعمال می‌شود) یا در سطح رویداد (که به شما امکان می‌دهد تنظیمات رضایت متفاوتی را برای رویدادهای منفرد تعیین کنید) تنظیم کنید.

نقشه‌برداری میدان ساختاری

جداول نگاشت زیر نحوه تبدیل فیلدهای مجزا از مشخصات ECAPI به فیلدهای پذیرفته شده توسط رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API) را تعریف می‌کنند.

نگاشت شیء رویداد

ایکاپی ( `event` )	رابط برنامه‌نویسی کاربردی مدیریت داده ( `Event` )	یادداشت‌ها
`data_set_id`	`destinations[].product_destination_id` (سطح درخواست) `destination_references` (سطح رویداد)	در سطوح زیر قابل تعریف است: سطح درخواست (الزامی) : لیست `destinations` را در `IngestEventsRequest` مشخص کنید. سطح رویداد: از فیلد `destination_references` در شیء `Event` استفاده کنید. یک ورودی اضافه کنید تا مشخص کنید کدام مقصد از لیست `destinations` باید رویداد را دریافت کند. برای اطلاعات بیشتر در مورد نحوه تعریف یک `Destination` و تعیین شناسه مقصد محصول، به پیکربندی مقصدها و سربرگ‌ها مراجعه کنید.
`id`	`transaction_id`	این مقدار برای حذف داده‌های تکراری از رویدادهای تبدیل استفاده می‌شود. اطلاعات بیشتر .
`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 تنظیم می‌شود.
`properties`	`cart_data` `custom_variables` `additional_event_parameters`	اقلام سطح تراکنش را می‌توان به آرایه `cart_data.items` در شیء `CartData` نگاشت کرد. رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API) از چندین فیلد اختیاری مرکز فروشندگان برای محصولاتی که در حساب‌های مرکز فروشندگان وجود دارند، پشتیبانی می‌کند. اگر هدف شما یک اقدام تبدیل گوگل ادز است، می‌توانید پارامترهای سفارشی اضافی را نیز در فیلد `custom_variables` به عنوان لیستی از اشیاء `CustomVariable` وارد کنید. اگر مقصد شما یک جریان داده گوگل آنالیتیکس است، می‌توانید پارامترهای رویداد اضافی را در فیلد `additional_event_parameters` به عنوان لیستی از اشیاء `AdditionalEventParameter` وارد کنید.
`ext`	معادلی وجود ندارد

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

در رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API)، فیلد user_data در شیء Event ، یک شیء UserData را می‌پذیرد. این شیء، فهرستی از اشیاء UserIdentifier دریافت می‌کند که می‌تواند شامل شناسه‌های کاربر مانند آدرس‌های ایمیل، شماره تلفن یا اجزای آدرس باشد.

ECAPI ( `user_data` )	رابط برنامه‌نویسی کاربردی مدیریت داده ( `Event` )	یادداشت‌ها
`customer_identifier`	`user_id` (گوگل آنالیتیکس)	برای رویدادهای گوگل آنالیتیکس، فیلد `user_id` نشان‌دهنده‌ی یک شناسه‌ی کاربری (User-ID ) است. رابط برنامه‌نویسی کاربردی (API) مدیریت داده (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 استفاده می‌کنید، می‌توانید آفست منطقه زمانی را مستقیماً در رشته `event_timestamp` RFC 3339 مشخص کنید. اگر از بافرهای پروتکل استفاده می‌کنید، می‌توانید از توابع کاربردی مانند `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`	به شناسه تلفن همراه برای تبلیغ‌کنندگان (IDFA در iOS، 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`	معادلی وجود ندارد

نگاشت شیء آدرس

ایکاپی ( `address` )	رابط برنامه‌نویسی کاربردی مدیریت داده ( `AddressInfo` )	یادداشت‌ها
`first_name`	`given_name`	به فیلد `given_name` در `AddressInfo` نگاشت می‌شود. دستورالعمل‌های قالب‌بندی و هش کردن را دنبال کنید. همچنین می‌توانید ویژگی‌های هش شده یک آدرس را رمزگذاری کنید .
`last_name`	`family_name`	به فیلد `family_name` در `AddressInfo` نگاشت می‌شود. دستورالعمل‌های قالب‌بندی و هش کردن را دنبال کنید. همچنین می‌توانید ویژگی‌های هش شده یک آدرس را رمزگذاری کنید .
`street`	معادلی وجود ندارد	در رابط برنامه‌نویسی کاربردی مدیریت داده پشتیبانی نمی‌شود
`city`	معادلی وجود ندارد	در رابط برنامه‌نویسی کاربردی مدیریت داده پشتیبانی نمی‌شود
`state`	معادلی وجود ندارد	در رابط برنامه‌نویسی کاربردی مدیریت داده پشتیبانی نمی‌شود
`country_code`	`region_code`	هش نکنید . به فیلد `region_code` در `AddressInfo` نگاشت می‌شود. دستورالعمل‌های قالب‌بندی را دنبال کنید.
`postal_code`	`postal_code`	هش نکنید . به فیلد `postal_code` در `AddressInfo` نگاشت می‌شود. دستورالعمل‌های قالب‌بندی را دنبال کنید.
`address_type`	معادلی وجود ندارد	در رابط برنامه‌نویسی کاربردی مدیریت داده پشتیبانی نمی‌شود
`ext`	معادلی وجود ندارد

نگاشت شیء مورد

ایکاپی ( `item` )	رابط برنامه‌نویسی کاربردی مدیریت داده ( `Item` )	یادداشت‌ها
`id`	`item_id`	برای رویدادهای گوگل آنالیتیکس الزامی است . برای هر آیتم، یک شناسه استاندارد و منحصر به فرد تنظیم کنید.
معادلی وجود ندارد	`merchant_product_id`	برای تبدیل‌های Floodlight و تبدیل‌های Google Ads با داده‌های سبد خرید مورد نیاز است . روی شناسه محصول در حساب مرکز فروشندگان تنظیم کنید.
`name`	`additional_item_parameters`	به عنوان `item_name` در لیست `additional_item_parameters` نگاشت کنید.
`price`	`unit_price`
`discount`	`additional_item_parameters` یا `custom_variables`	به عنوان `discount` در `additional_item_parameters` (برای گوگل آنالیتیکس) یا به عنوان یک متغیر سفارشی در `custom_variables` (برای گوگل ادز) نگاشت کنید.
`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 به شدت با قراردادهای نامگذاری گوگل آنالیتیکس همسو هستند.

اگر رویدادها را به جریان داده گوگل آنالیتیکس ارسال می‌کنید، فیلد event_name الزامی است.
برای مشاهده‌ی فیلدها، پارامترها و نمونه‌های درخواست‌های ورودی API مربوط به هر رویداد، به مرجع رویدادهای پیشنهادی گوگل آنالیتیکس مراجعه کنید.
همچنین می‌توانید رویدادهای سفارشی ارسال کنید، مشروط بر اینکه از قوانین نامگذاری رویداد پیروی کنند.

اکثر رویدادهای استاندارد ECAPI (مانند purchase ، add_to_cart ، begin_checkout ، search و refund ) نام رویداد مشابهی با رویدادهای توصیه‌شده توسط گوگل آنالیتیکس دارند. با این حال، چند استثنا وجود دارد که در آن‌ها گوگل آنالیتیکس به جای گذشته از زمان حال استفاده می‌کند:

نقشه‌های viewed_item به view_item
نقشه‌های viewed_item_list به view_item_list
نقشه‌های viewed_cart به view_cart

درخواست‌های نمونه

تب‌های زیر مقایسه‌ای بین یک رویداد تبدیل ECAPI و نمایش آن به عنوان یک درخواست معتبر IngestEventsRequest از رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API) را نشان می‌دهند.

ایکاپی

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