Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

ربط مواصفات ECAPI

يساعد هذا الدليل المطوّرين الذين يستخدمون مواصفات Event and Conversion API (ECAPI) من IAB Tech Lab في ربط بيانات الأحداث والإحالات الناجحة بمخطط استيعاب الأحداث في Data Manager API.

نظرة عامة

‫ECAPI هو معيار بيانات مفتوح المصدر ومستقل عن أي منصة، وهو مصمّم لتحديد طريقة تنظيم الأحداث والإحالات الناجحة المرتبطة بالتسويق.

يقدّم الجدول التالي نظرة عامة على مستوى عالٍ حول كيفية مقارنة السمات الرئيسية ومبادئ التصميم الخاصة بواجهة ECAPI بواجهة Data Manager API.

	ECAPI	Data Manager API
إزالة التكرار	تعتمد على `id` (رقم تعريف الحدث)	تعتمد على `transaction_id`
توجيه الأحداث	يتم تحديد وجهة البيانات من خلال الحقل `data_set_id` في حمولة الحدث.	يحدّد الحقل `destinations` في الطلب الوجهات الخاصة بالأحداث. تتيح Data Manager API أيضًا توجيه الأحداث إلى وجهات متعدّدة في طلب واحد. اطّلِع على دليل الوجهات للحصول على مزيد من المعلومات.
حقول الخصوصية والموافقة	سلاسل الموافقة في إطار عمل Global Privacy Platform‏ (GPP)	لا تقبل واجهة برمجة التطبيقات Data Manager API سلاسل الموافقة الخاصة بإطار عمل Global Privacy Platform (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`	تُستخدَم هذه القيمة لإزالة تكرار أحداث الإحالات الناجحة. مزيد من المعلومات
`timestamp`	`event_timestamp`	مطلوبة تستخدِم واجهة برمجة التطبيقات للإحالات الناجحة المحسّنة تنسيق حقبة Unix (عدد صحيح) للطوابع الزمنية. عند الربط بـ 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"، يمكنك أيضًا تضمين مَعلمات مخصّصة إضافية في الحقل `custom_variables` كقائمة عناصر `CustomVariable`. إذا كانت وجهتك هي مصدر بيانات "إحصاءات Google"، يمكنك تضمين معلّمات أحداث إضافية في الحقل `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)	بالنسبة إلى أحداث "إحصاءات Google"، يمثّل الحقل `user_id` معرّف المستخدم. لا تتيح واجهة برمجة التطبيقات Data Manager حقول معرّف العميل العامة لوجهات أخرى.
`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`. راجِع ربط عنصر العنوان.
`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". يجب ضبطها على معرّف فريد وموحّد للعنصر.
بدون مكافئ	`merchant_product_id`	مطلوب للإحالات الناجحة في Floodlight والإحالات الناجحة في "إعلانات Google" التي تتضمّن بيانات سلة التسوّق. اضبط هذا الحقل على معرّف المنتج ضمن حساب 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") أو كمتغيّر مخصّص في `custom_variables` (لخدمة "إعلانات Google")
`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".

إذا كنت ترسِل أحداثًا إلى مصدر بيانات "إحصاءات Google"، يكون الحقل event_name مطلوبًا.
راجِع مرجع الأحداث المقترَحة في "إحصاءات Google" للاطّلاع على الحقول والمَعلمات وطلبات الاستيعاب النموذجية في Data Manager API المرتبطة بكل حدث.
يمكنك أيضًا إرسال أحداث مخصّصة شرط أن تتّبع قواعد تسمية الأحداث.

تتضمّن معظم الأحداث العادية لواجهة برمجة التطبيقات ECAPI (مثل purchase وadd_to_cart وbegin_checkout وsearch وrefund) اسم الحدث نفسه كما هو الحال في الأحداث المقترَحة في "إحصاءات Google". ومع ذلك، هناك بعض الاستثناءات التي تستخدم فيها "إحصاءات Google" صيغة المضارع بدلاً من صيغة الماضي:

viewed_item خريطة إلى view_item
viewed_item_list خرائط إلى view_item_list
viewed_cart خريطة إلى view_cart

أمثلة على الطلبات

تعرض علامات التبويب التالية مقارنة بين حمولة حدث إحالة ناجحة في واجهة ECAPI وتمثيلها كـ IngestEventsRequest صالح في Data Manager API.

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
      }
    ]
  }
}

Data Manager API

في ما يلي نموذج IngestEventsRequest لبيانات الحدث المنسَّقة والمجزّأة والمشفّرة. هذا النموذج مخصّص لوجهة "إعلانات Google"، كما هو موضّح في نوع الحساب 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
          }
        ]
      }
    }
  ]
}