ربط مواصفات ECAPI

يساعد هذا الدليل المطوّرين الذين يستخدمون مواصفات IAB Tech Lab Event and Conversion API (ECAPI) في ربط بيانات الأحداث والإحالات الناجحة بمخطط استيعاب الأحداث في 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 تنسيق حقبة Unix (عدد صحيح) للطوابع الزمنية. عند الربط بواجهة 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
          }
        ]
      }
    }
  ]
}