ربط مواصفات 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 تزيل التكرار في أحداث الإحالات الناجحة. اطّلِع على طريقة معالجة Google للبيانات المتعدّدة المصادر في أدلة إرسال الأحداث لكلّ من إعلانات Google وإحصاءات Google وFloodlight.
timestamp event_timestamp هذا العنصر مطلوب. تستخدم واجهة ECAPI تنسيق حقبة يونكس (عدد صحيح) للطوابع الزمنية. عند الربط بواجهة Data Manager API، يجب تحويل الحقل event_timestamp إلى أحد التنسيقات التالية:
  • في حال استخدام تنسيق JSON، اضبط القيمة على تنسيق RFC 3339.
  • في حال استخدام Protocol Buffers، استخدِم 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 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.
إذا كنت تستخدم Protocol Buffers، يمكنك استخدام دوال خدمية مثل 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".

تحمل معظم الأحداث العادية في 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 وتمثيلها كطلب صالح في 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
      }
    ]
  }
}

Data Manager API

في ما يلي نموذج IngestEventsRequest لبيانات الأحداث المنسَّقة والمجزّأة والمشفّرة. يشير نوع حساب GOOGLE_ADS في الوجهة إلى أنّ الطلب يستهدف وجهة في "إعلانات Google":

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