ربط مواصفات 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 معرّف 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".

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