تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

ربط مواصفات ECAPI

يساعد هذا الدليل المطوّرين الذين يستخدمون مواصفات واجهة برمجة التطبيقات الخاصة بالأحداث والإحالات الناجحة (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`	هذا العنصر مطلوب. تستخدِم واجهة برمجة التطبيقات ECAPI تنسيق حقبة 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` 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، يمكنك تحديد إزاحة المنطقة الزمنية مباشرةً في السلسلة `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`	يجب الربط بمعرّف المعلِنين على الأجهزة الجوّالة (معرّف المعلِنين على iOS أو المعرّف الإعلاني على 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 المرتبطة بكل حدث.
يمكنك أيضًا إرسال أحداث مخصّصة شرط أن تتّبع قواعد تسمية الأحداث.

تتضمّن معظم الأحداث العادية في واجهة برمجة التطبيقات للإحالات الناجحة المحسّنة (مثل 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
          }
        ]
      }
    }
  ]
}