الأحداث المقترَحة في "إحصاءات Google"

في ما يلي قائمة بالأحداث المقترَحة. يمكنك أيضًا إنشاء أحداث مخصّصة وإرسالها.

عند إنشاء أسماء أحداث مخصّصة، يجب:

  1. اتّبِع قواعد تسمية الأحداث.
  2. تجنَّب الأسماء والبادئات المحجوزة.
  3. الالتزام بحدود جمع الأحداث، مثل الحدّ الأقصى لعدد الأحرف المسموح به لأسماء الأحداث والمَعلمات وهو 40 حرفًا

يُرجى الاطّلاع على مقالة البدء لمزيد من التفاصيل.

إذا كنت تجري ترقية من Measurement Protocol، اطّلِع على الترقية من Measurement Protocol للحصول على التعليمات.

بالنسبة إلى جميع المواقع

ad_impression

لا يتوفّر هذا الحدث إلا لمصادر بيانات التطبيقات.

استخدِم هذا الحدث عندما يرى مستخدم مرة ظهور للإعلان.

  • لن يتم تضمين أي ad_impression يتم إرساله باستخدام Measurement Protocol في عمليات التصدير إلى المنصات الإعلانية الأخرى، مثل "إعلانات Google".
  • يمكن أن يؤدي إرسال أحداث ad_impression باستخدام Measurement Protocol إلى تكرار مرات الظهور إذا كنت قد أعددت وضع العلامات أو حزمة تطوير البرامج (SDK) لمنتجات Google الإعلانية المرتبطة. يجب إرسال حدث ad_impression باستخدام Measurement Protocol فقط إذا لم يتم تسجيل الحدث من خلال وضع العلامات أو حزمة تطوير البرامج (SDK).

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string لا دولار أمريكي عملة السلع المرتبطة بالحدث، بتنسيق ISO 4217 المُكوَّن من 3 أحرف.

* في حال ضبط مَعلمة conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الأرباح بدقة.
conversion_value number لا يورو ‫
قيمة ظهور الإعلان
* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
ad_platform string لا MoPub المنصة الإعلانية
ad_source string لا AdColony مصدر الإعلان
ad_format string لا بانر شكل الإعلان
ad_unit_name string لا Banner_03 اسم الوحدة الإعلانية

مثال

يوضّح المثال التالي كيفية إرسال حدث ad_impression باستخدام Data Manager API. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "FIREBASE_APP_ID"
    }
  ],
  "events": [
    {
      "eventName": "ad_impression",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "APP",
      "appInstanceId": "APP_INSTANCE_ID",
      "currency": "USD",
      "conversionValue": 3.99,
      "additionalEventParameters": [
        {
          "parameterName": "ad_platform",
          "value": "MoPub"
        },
        {
          "parameterName": "ad_source",
          "value": "AdColony"
        },
        {
          "parameterName": "ad_format",
          "value": "Banner"
        },
        {
          "parameterName": "ad_unit_name",
          "value": "Banner_03"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "app_instance_id": "app_instance_id",
    "events": [{
      "name": "ad_impression",
      "params": {
        "ad_platform": "MoPub",
        "ad_source": "AdColony",
        "ad_format": "Banner",
        "ad_unit_name": "Banner_03",
        "currency": "USD",
        "value": 3.99
      }
    }]
  })
});

earn_virtual_currency

يقيس هذا الحدث الحالات التي يحصل فيها المستخدم على عملة افتراضية في لعبة معيّنة. يمكنك تسجيل هذا الحدث مع spend_virtual_currency لفهم اقتصادك الافتراضي بشكلٍ أفضل.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
conversion_value number لا 5 قيمة العملة الافتراضية

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
virtual_currency_name string لا Gems اسم العملة الافتراضية.

مثال

يوضّح المثال التالي كيفية إرسال حدث earn_virtual_currency باستخدام Data Manager API. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "earn_virtual_currency",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "conversionValue": 5,
      "additionalEventParameters": [
        {
          "parameterName": "virtual_currency_name",
          "value": "Gems"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "earn_virtual_currency",
      "params": {
        "virtual_currency_name": "Gems",
        "value": 5
      }
    }]
  })
});

join_group

سجِّل هذا الحدث عندما ينضمّ مستخدم إلى مجموعة، مثل رابطة أو فريق أو عائلة. يمكنك استخدام هذا الحدث لتحليل مدى رواج مجموعات أو ميزات اجتماعية معيّنة.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
group_id string لا G_12345 رقم تعريف المجموعة

مثال

يوضّح المثال التالي كيفية إرسال حدث join_group باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "join_group",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "additionalEventParameters": [
        {
          "parameterName": "group_id",
          "value": "G_12345"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events":[{
      "name":"join_group",
      "params":{
        "group_id":"G_12345"
      }
    }]
  })
});

login

أرسِل هذا الحدث للإشارة إلى أنّ مستخدمًا قد سجّل الدخول إلى موقعك الإلكتروني أو تطبيقك.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
method string لا Google الطريقة المستخدَمة لتسجيل الدخول

مثال

يوضّح المثال التالي كيفية إرسال حدث login باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "login",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "additionalEventParameters": [
        {
          "parameterName": "method",
          "value": "Google"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "login",
      "params": {
        "method": "Google"
      }
    }]
  })
});

screen_view

لا يتوفّر هذا الحدث إلا لمصادر بيانات التطبيقات.

استخدِم هذا الحدث للإشارة إلى حدوث انتقال بين الشاشات.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
screen_class string لا MainActivity فئة الشاشة
screen_name string لا لمحة اسم الشاشة.

مثال

يوضّح المثال التالي كيفية إرسال حدث screen_view باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "FIREBASE_APP_ID"
    }
  ],
  "events": [
    {
      "eventName": "screen_view",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "APP",
      "appInstanceId": "APP_INSTANCE_ID",
      "additionalEventParameters": [
        {
          "parameterName": "screen_class",
          "value": "MainActivity"
        },
        {
          "parameterName": "screen_name",
          "value": "About"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "app_instance_id": "app_instance_id",
    "events": [{
      "name": "screen_view",
      "params": {
        "screen_class": "MainActivity",
        "screen_name": "About"
      }
    }]
  })
});

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

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
search_term string نعم قمصان العبارة التي تم البحث عنها.

مثال

يوضّح المثال التالي كيفية إرسال حدث search باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "search",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "additionalEventParameters": [
        {
          "parameterName": "search_term",
          "value": "t-shirts"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "search",
      "params": {
        "search_term": "t-shirts"
      }
    }]
  })
});

select_content

يشير هذا الحدث إلى أنّ المستخدِم قد اختار محتوًى من نوع معيّن. يمكن أن يساعدك هذا الحدث في تحديد المحتوى الرائج وفئات المحتوى على موقعك الإلكتروني أو تطبيقك.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
content_type string لا المنتج نوع المحتوى المحدّد
content_id string لا C_12345 معرّف للمحتوى الذي تمّ اختياره يجب أن تتضمّن القيمة حرفًا واحدًا على الأقل غير رقمي.

مثال

يوضّح المثال التالي كيفية إرسال حدث select_content باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "select_content",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "additionalEventParameters": [
        {
          "parameterName": "content_type",
          "value": "product"
        },
        {
          "parameterName": "content_id",
          "value": "C_12345"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "select_content",
      "params": {
        "content_type": "product",
        "content_id": "C_12345"
      }
    }]
  })
});

share

استخدِم هذا الحدث عندما يشارك مستخدم محتوى.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
cart_data.items Item[] لا السلع الخاصة بالحدث

اضبط الحقل cart_data.items على العنصر Event.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
method string لا Twitter الطريقة التي تتم بها مشاركة المحتوى
content_type string لا الصورة نوع المحتوى المشترَك

مثال

يوضّح المثال التالي كيفية إرسال حدث share باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "share",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "cartData": {
        "items": [
          {
            "itemId": "C_12345",
            "quantity": 1,
            "unitPrice": 27.67
          }
        ]
      },
      "additionalEventParameters": [
        {
          "parameterName": "method",
          "value": "Twitter"
        },
        {
          "parameterName": "content_type",
          "value": "image"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "share",
      "params": {
        "method": "Twitter",
        "content_type": "image",
        "item_id": "C_12345"
      }
    }]
  })
});

sign_up

يشير هذا الحدث إلى أنّ مستخدمًا قد اشترك لإنشاء حساب. يمكنك استخدام هذا الحدث لفهم السلوكيات المختلفة للمستخدمين الذين سجّلوا دخولهم وسجّلوا خروجهم.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
method string لا Google الطريقة المستخدَمة للاشتراك

مثال

يوضّح المثال التالي كيفية إرسال حدث sign_up باستخدام واجهة برمجة التطبيقات "إدارة بيانات إعلانات Google". في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "sign_up",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "additionalEventParameters": [
        {
          "parameterName": "method",
          "value": "Google"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "sign_up",
      "params": {
        "method": "Google"
      }
    }]
  })
});

spend_virtual_currency

يقيس هذا الحدث مبيعات السلع الافتراضية في تطبيقك ويساعدك في تحديد السلع الافتراضية الأكثر رواجًا.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
conversion_value number نعم 5 قيمة العملة الافتراضية
cart_data.items Item[] لا السلع الخاصة بالحدث

اضبط الحقل cart_data.items على العنصر Event.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

مَعلمات المنتج أو الخدمة

الاسم النوع مطلوب مثال على القيمة الوصف
item_name string لا Starter Boost اسم السلعة التي يتم استخدام العملة الافتراضية لشرائها

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
virtual_currency_name string نعم Gems اسم العملة الافتراضية.

مثال

يوضّح المثال التالي كيفية إرسال حدث spend_virtual_currency باستخدام Data Manager API. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "spend_virtual_currency",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "cartData": {
        "items": [
          {
            "itemId": "I_12345",
            "quantity": 1,
            "unitPrice": 27.67,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Starter Boost"
              }
            ]
          }
        ]
      },
      "conversionValue": 5,
      "additionalEventParameters": [
        {
          "parameterName": "virtual_currency_name",
          "value": "Gems"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "spend_virtual_currency",
      "params": {
        "value": 5,
        "virtual_currency_name": "Gems",
        "item_name": "Starter Boost"
      }
    }]
  })
});

tutorial_begin

يشير هذا الحدث إلى بدء عملية الإعداد. يمكنك استخدام هذا الحدث في مسار إحالة ناجحة مع tutorial_complete لمعرفة عدد المستخدمين الذين أكملوا الدليل التوجيهي.

المعلمات

ما مِن مَعلمات مقترَحة لهذا الحدث.

مثال

يوضّح المثال التالي كيفية إرسال حدث tutorial_begin باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "tutorial_begin",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID"
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "tutorial_begin"
    }]
  })
});

tutorial_complete

يشير هذا الحدث إلى إكمال المستخدم لعملية الإعداد. استخدِم هذا الحدث في مسار الإحالة الناجحة مع الحدث tutorial_begin لمعرفة عدد المستخدِمين الذين يكملون الدليل التوجيهي.

المعلمات

ما مِن مَعلمات مقترَحة لهذا الحدث.

مثال

يوضّح المثال التالي كيفية إرسال حدث tutorial_complete باستخدام Data Manager API. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "tutorial_complete",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID"
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "tutorial_complete"
    }]
  })
});

view_search_results

سجِّل هذا الحدث عندما تظهر للمستخدم نتائج البحث. يُرجى العِلم أنّه يمكنك تفعيل حدث view_search_results لجمعه تلقائيًا من خلال القياس المحسّن للأحداث في "إحصاءات Google".

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
search_term string لا ملابس العبارة المستخدَمة للبحث.

مثال

يوضّح المثال التالي كيفية إرسال حدث view_search_results باستخدام Data Manager API. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "view_search_results",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "additionalEventParameters": [
        {
          "parameterName": "search_term",
          "value": "Clothing"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "view_search_results",
      "params": {
        "search_term": "Clothing"
      }
    }]
  })
});

campaign_details

استخدِم هذا الحدث لإرسال تفاصيل الحملة التي سيتم تطبيقها على الأحداث التي لها طابع زمني أكبر من أو يساوي الطابع الزمني للحدث campaign_details.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
campaign_id string لا google_1234 رقم تعريف الحملة
campaign string لا Summer_fun الاسم المستخدَم لتحديد عرض ترويجي أو حملة استراتيجية معيّنة.
source string لا google مصدر زيارات الحملة (مثل google والبريد الإلكتروني وما إلى ذلك)
medium string لا تكلفة النقرة وسيط الحملة (مثل البريد الإلكتروني أو تكلفة النقرة أو غير ذلك)
term string لا summer+travel عبارة الحملة المستخدَمة مع نتائج البحث المدفوعة لتوفير الكلمات الرئيسية للإعلانات
content string لا logolink محتوى الحملة المستخدَم لاختبارات A/B والإعلانات التي تستهدف المحتوى لتمييز الإعلانات أو الروابط التي تشير إلى عنوان URL نفسه.

مثال

يوضّح المثال التالي كيفية إرسال حدث campaign_details باستخدام Data Manager API. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "campaign_details",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "additionalEventParameters": [
        {
          "parameterName": "campaign_id",
          "value": "google_1234"
        },
        {
          "parameterName": "campaign",
          "value": "Summer_fun"
        },
        {
          "parameterName": "source",
          "value": "google"
        },
        {
          "parameterName": "medium",
          "value": "cpc"
        },
        {
          "parameterName": "term",
          "value": "summer+travel"
        },
        {
          "parameterName": "content",
          "value": "logolink"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "campaign_details",
      "params": {
        "campaign_id": "google_1234",
        "campaign": "Summer_fun",
        "source": "google",
        "medium": "cpc",
        "term": "summer+travel",
        "content": "logolink"
      }
    }]
  })
});

المبيعات على الإنترنت

add_payment_info

يشير هذا الحدث إلى أنّ المستخدم قد أرسل معلومات الدفع في عملية دفع للتجارة الإلكترونية.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة السلع المرتبطة بالحدث، بتنسيق ISO 4217 المُكوَّن من 3 أحرف.

* لا تساهم مقاييس القيمة في الحدث view_item في الإيرادات

* في حال ضبط conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الإيرادات بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* اضبط conversion_value على مجموع (price * quantity) لجميع العناصر في items. لا تُدرِج shipping أو tax.
* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث على أنّه حدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.
cart_data.items Item[] نعم السلع الخاصة بالحدث

اضبط الحقل cart_data.items على العنصر Event.
cart_data.coupon_codes string[] لا SUMMER_FUN رمز القسيمة المرتبط بالحدث


اضبط الحقل coupon_codes في العنصر CartData.
* يجب تقديم رمز قسيمة واحد فقط في هذه القائمة.
* لا يرتبط هذا الحقل برموز القسائم على مستوى السلعة.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
payment_type string لا بطاقة ائتمان طريقة الدفع التي تم اختيارها

مثال

يوضّح المثال التالي كيفية إرسال حدث add_payment_info باستخدام Data Manager API. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "add_payment_info",
      "conversionValue": 30.03,
      "currency": "USD",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "additionalEventParameters": [
        {
          "parameterName": "payment_type",
          "value": "Credit Card"
        }
      ],
      "cartData": {
        "couponCodes": [
          "SUMMER_FUN"
        ],
        "items": [
          {
            "itemId": "SKU_12345",
            "quantity": 1,
            "unitPrice": 29.99,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Triblend Android T-Shirt"
              }
            ]
          }
        ]
      }
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "add_payment_info",
      "params": {
        "currency": "USD",
        "value": 30.03,
        "coupon": "SUMMER_FUN",
        "payment_type": "Credit Card",
        "items": [
          {
            "item_id": "SKU_12345",
            "item_name": "Stan and Friends Tee",
            "affiliation": "Google Merchandise Store",
            "coupon": "SUMMER_FUN",
            "currency": "USD",
            "discount": 2.22,
            "index": 0,
            "item_brand": "Google",
            "item_category": "Apparel",
            "item_category2": "Adult",
            "item_category3": "Shirts",
            "item_category4": "Crew",
            "item_category5": "Short sleeve",
            "item_list_id": "related_products",
            "item_list_name": "Related Products",
            "item_variant": "green",
            "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
            "price": 10.01,
            "google_business_vertical": "retail",
            "quantity": 3
          }
        ]
      }
    }]
  })
});

add_shipping_info

يشير هذا الحدث إلى أنّ المستخدم قد أرسل معلومات الشحن في عملية دفع للتجارة الإلكترونية.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة السلع المرتبطة بالحدث، بتنسيق ISO 4217 المُكوَّن من 3 أحرف.

* لا تساهم مقاييس القيمة في الحدث view_item في الإيرادات

* في حال ضبط conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الإيرادات بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* اضبط conversion_value على مجموع (price * quantity) لجميع العناصر في items. لا تُدرِج shipping أو tax.
* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث على أنّه حدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.
cart_data.items Item[] نعم السلع الخاصة بالحدث

اضبط الحقل cart_data.items على العنصر Event.
cart_data.coupon_codes string[] لا SUMMER_FUN رمز القسيمة المرتبط بالحدث


اضبط الحقل coupon_codes في العنصر CartData.
* يجب تقديم رمز قسيمة واحد فقط في هذه القائمة.
* لا علاقة لذلك برموز القسائم على مستوى السلعة.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
shipping_tier string لا أرض فئة الشحن (على سبيل المثال Ground أو Air أو Next-day) التي تم اختيارها لتسليم السلعة المشتراة.

مثال

يوضّح المثال التالي كيفية إرسال حدث add_shipping_info باستخدام Data Manager API. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "add_shipping_info",
      "conversionValue": 30.03,
      "currency": "USD",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "additionalEventParameters": [
        {
          "parameterName": "shipping_tier",
          "value": "Ground"
        }
      ],
      "cartData": {
        "couponCodes": [
          "SUMMER_FUN"
        ],
        "items": [
          {
            "itemId": "SKU_12345",
            "quantity": 1,
            "unitPrice": 29.99,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Triblend Android T-Shirt"
              }
            ]
          }
        ]
      }
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "add_shipping_info",
      "params": {
        "currency": "USD",
        "value": 30.03,
        "coupon": "SUMMER_FUN",
        "shipping_tier": "Ground",
        "items": [
          {
            "item_id": "SKU_12345",
            "item_name": "Stan and Friends Tee",
            "affiliation": "Google Merchandise Store",
            "coupon": "SUMMER_FUN",
            "currency": "USD",
            "discount": 2.22,
            "index": 0,
            "item_brand": "Google",
            "item_category": "Apparel",
            "item_category2": "Adult",
            "item_category3": "Shirts",
            "item_category4": "Crew",
            "item_category5": "Short sleeve",
            "item_list_id": "related_products",
            "item_list_name": "Related Products",
            "item_variant": "green",
            "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
            "price": 10.01,
            "google_business_vertical": "retail",
            "quantity": 3
          }
        ]
      }
    }]
  })
});

add_to_cart

يشير هذا الحدث إلى أنّه تمت إضافة سلعة إلى سلة التسوّق لشرائها.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة السلع المرتبطة بالحدث، بتنسيق ISO 4217 المُكوَّن من 3 أحرف.

* لا تساهم مقاييس القيمة في الحدث view_item في الإيرادات

* في حال ضبط conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الإيرادات بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* اضبط conversion_value على مجموع (price * quantity) لجميع العناصر في items. لا تُدرِج shipping أو tax.
* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث كحدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.
cart_data.items Item[] نعم السلع الخاصة بالحدث

اضبط الحقل cart_data.items على العنصر Event.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

مَعلمات المنتج أو الخدمة

الاسم النوع مطلوب مثال على القيمة الوصف
item_name string نعم* قميص Stan and Friends

اسم السلعة.

*يجب توفير إما item_id أو item_name.

affiliation string لا Google Store ارتباط المنتج لتحديد الشركة التي تقدّمه أو الموقع الجغرافي للمتجر الذي يقدّمه
ملاحظة: لا يتوفّر affiliation إلا على مستوى المنتج أو الخدمة.
coupon string لا SUMMER_FUN اسم/رمز القسيمة المرتبط بالسلعة

تكون مَعلمات coupon على مستوى الحدث وعلى مستوى السلعة مستقلة.
discount number لا 2.22 قيمة الخصم النقدي للوحدة المرتبطة بالسلعة
index number لا 5 تمثّل هذه السمة فهرس/موضع السلعة في القائمة.
item_brand string لا Google العلامة التجارية للسلعة
item_category string لا ملابس فئة السلعة إذا تم استخدامها كجزء من تسلسل هرمي للفئات أو تصنيف، ستكون هذه الفئة الأولى.
item_category2 string لا للبالغين التسلسل الهرمي للفئة الثانية أو التصنيف الإضافي للسلعة
item_category3 string لا قمصان التسلسل الهرمي للفئة الثالثة أو التصنيف الإضافي للسلعة
item_category4 string لا طاقم العمل التسلسل الهرمي للفئة الرابعة أو التصنيف الإضافي للسلعة
item_category5 string لا كُم قصير التسلسل الهرمي للفئة الخامسة أو التصنيف الإضافي للسلعة
item_list_id string لا related_products رقم تعريف القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_id على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_id على مستوى الحدث، في حال توفّرها.
item_list_name string لا المنتجات ذات الصلة اسم القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_name على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_name على مستوى الحدث، في حال توفّرها.
item_variant string لا أخضر صيغة العنصر أو رمز فريد أو وصف لمزيد من التفاصيل/خيارات العناصر
location_id string لا ChIJIQBpAG2ahYAR_6128GcTUEo (رقم تعريف المكان في Google لمدينة سان فرانسيسكو) الموقع الجغرافي المرتبط بالسلعة (مثل الموقع الجغرافي للمتجر). ننصحك باستخدام رقم تعريف المكان على Google الذي يتوافق مع العنصر المرتبط. ويمكن أيضًا استخدام معرّف موقع جغرافي مخصّص.
ملاحظة: لا يتوفّر العنصر location_id إلا على مستوى المنتج أو الخدمة.
بالإضافة إلى المَعلمات المحدّدة، يمكنك تضمين ما يصل إلى 27 مَعلمة مخصّصة في مصفوفة items.

مثال

يوضّح المثال التالي كيفية إرسال حدث add_to_cart باستخدام واجهة برمجة التطبيقات لإدارة بيانات "إعلانات Google". في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "add_to_cart",
      "conversionValue": 30.03,
      "currency": "USD",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "cartData": {
        "items": [
          {
            "itemId": "SKU_12345",
            "quantity": 1,
            "unitPrice": 29.99,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Triblend Android T-Shirt"
              }
            ]
          }
        ]
      }
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "add_to_cart",
      "params": {
        "currency": "USD",
        "value": 30.03,
        "items": [
          {
            "item_id": "SKU_12345",
            "item_name": "Stan and Friends Tee",
            "affiliation": "Google Merchandise Store",
            "coupon": "SUMMER_FUN",
            "currency": "USD",
            "discount": 2.22,
            "index": 0,
            "item_brand": "Google",
            "item_category": "Apparel",
            "item_category2": "Adult",
            "item_category3": "Shirts",
            "item_category4": "Crew",
            "item_category5": "Short sleeve",
            "item_list_id": "related_products",
            "item_list_name": "Related Products",
            "item_variant": "green",
            "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
            "price": 10.01,
            "google_business_vertical": "retail",
            "quantity": 3
          }
        ]
      }
    }]
  })
});

add_to_wishlist

يشير هذا الحدث إلى أنّه تمت إضافة منتج إلى قائمة أمنيات. استخدِم هذا الحدث لتحديد الهدايا الرائجة في تطبيقك.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة السلع المرتبطة بالحدث، بتنسيق ISO 4217 المُكوَّن من 3 أحرف.

* لا تساهم مقاييس القيمة في الحدث view_item في الإيرادات

* في حال ضبط conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الإيرادات بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* اضبط conversion_value على مجموع (price * quantity) لجميع العناصر في items. لا تُدرِج shipping أو tax.
* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث كحدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.
cart_data.items Item[] نعم السلع الخاصة بالحدث

اضبط الحقل cart_data.items في العنصر Event.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

مَعلمات المنتج أو الخدمة

الاسم النوع مطلوب مثال على القيمة الوصف
item_name string نعم* قميص Stan and Friends

اسم السلعة.

*يجب توفير إما item_id أو item_name.

affiliation string لا Google Store ارتباط المنتج لتحديد الشركة التي تقدّمه أو الموقع الجغرافي للمتجر الذي يقدّمه
ملاحظة: لا يتوفّر affiliation إلا على مستوى المنتج أو الخدمة.
coupon string لا SUMMER_FUN اسم/رمز القسيمة المرتبط بالسلعة

تكون مَعلمات coupon على مستوى الحدث وعلى مستوى السلعة مستقلة.
discount number لا 2.22 قيمة الخصم النقدي للوحدة المرتبطة بالسلعة
index number لا 5 تمثّل هذه السمة فهرس/موضع السلعة في القائمة.
item_brand string لا Google العلامة التجارية للسلعة
item_category string لا ملابس فئة السلعة إذا تم استخدامها كجزء من تسلسل هرمي للفئات أو تصنيف، ستكون هذه الفئة الأولى.
item_category2 string لا للبالغين التسلسل الهرمي للفئة الثانية أو التصنيف الإضافي للسلعة
item_category3 string لا قمصان التسلسل الهرمي للفئة الثالثة أو التصنيف الإضافي للسلعة
item_category4 string لا طاقم العمل التسلسل الهرمي للفئة الرابعة أو التصنيف الإضافي للسلعة
item_category5 string لا كُم قصير التسلسل الهرمي للفئة الخامسة أو التصنيف الإضافي للسلعة
item_list_id string لا related_products رقم تعريف القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_id على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_id على مستوى الحدث، في حال توفّرها.
item_list_name string لا المنتجات ذات الصلة اسم القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_name على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_name على مستوى الحدث، في حال توفّرها.
item_variant string لا أخضر صيغة العنصر أو رمز فريد أو وصف لمزيد من التفاصيل/خيارات العناصر
location_id string لا ChIJIQBpAG2ahYAR_6128GcTUEo (رقم تعريف المكان في Google لمدينة سان فرانسيسكو) الموقع الجغرافي المرتبط بالسلعة (مثل الموقع الجغرافي للمتجر). ننصحك باستخدام رقم تعريف المكان على Google الذي يتوافق مع العنصر المرتبط. ويمكن أيضًا استخدام معرّف موقع جغرافي مخصّص.
ملاحظة: لا تتوفّر السمة location_id إلا على مستوى المنتج أو الخدمة.
بالإضافة إلى المَعلمات المحدّدة، يمكنك تضمين ما يصل إلى 27 مَعلمة مخصّصة في مصفوفة items.

مثال

يوضّح المثال التالي كيفية إرسال حدث add_to_wishlist باستخدام واجهة برمجة التطبيقات "إدارة بيانات إعلانات Google". في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "add_to_wishlist",
      "conversionValue": 30.03,
      "currency": "USD",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "cartData": {
        "items": [
          {
            "itemId": "SKU_12345",
            "quantity": 1,
            "unitPrice": 29.99,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Triblend Android T-Shirt"
              }
            ]
          }
        ]
      }
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "add_to_wishlist",
      "params": {
        "currency": "USD",
        "value": 30.03,
        "items": [
          {
            "item_id": "SKU_12345",
            "item_name": "Stan and Friends Tee",
            "affiliation": "Google Merchandise Store",
            "coupon": "SUMMER_FUN",
            "currency": "USD",
            "discount": 2.22,
            "index": 0,
            "item_brand": "Google",
            "item_category": "Apparel",
            "item_category2": "Adult",
            "item_category3": "Shirts",
            "item_category4": "Crew",
            "item_category5": "Short sleeve",
            "item_list_id": "related_products",
            "item_list_name": "Related Products",
            "item_variant": "green",
            "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
            "price": 10.01,
            "google_business_vertical": "retail",
            "quantity": 3
          }
        ]
      }
    }]
  })
});

begin_checkout

يشير هذا الحدث إلى أنّ المستخدم قد بدأ عملية دفع.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة السلع المرتبطة بالحدث، بتنسيق ISO 4217 المُكوَّن من 3 أحرف.

* لا تساهم مقاييس القيمة في الحدث view_item في الإيرادات

* في حال ضبط conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الإيرادات بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* اضبط conversion_value على مجموع (price * quantity) لجميع العناصر في items. لا تُدرِج shipping أو tax.
* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث كحدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.
cart_data.items Item[] نعم السلع الخاصة بالحدث

اضبط الحقل cart_data.items في العنصر Event.
cart_data.coupon_codes string[] لا SUMMER_FUN رمز القسيمة المرتبط بالحدث


اضبط الحقل coupon_codes في العنصر CartData.
* يجب تقديم رمز قسيمة واحد فقط في هذه القائمة.
* لا يرتبط هذا الحقل برموز القسائم على مستوى السلعة.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

مَعلمات المنتج أو الخدمة

الاسم النوع مطلوب مثال على القيمة الوصف
item_name string نعم* قميص Stan and Friends

اسم السلعة.

*يجب توفير إما item_id أو item_name.

affiliation string لا Google Store ارتباط المنتج لتحديد الشركة التي تقدّمه أو الموقع الجغرافي للمتجر الذي يقدّمه
ملاحظة: لا يتوفّر affiliation إلا على مستوى المنتج أو الخدمة.
coupon string لا SUMMER_FUN اسم/رمز القسيمة المرتبط بالسلعة

تكون مَعلمات coupon على مستوى الحدث وعلى مستوى السلعة مستقلة.
discount number لا 2.22 قيمة الخصم النقدي للوحدة المرتبطة بالسلعة
index number لا 5 تمثّل هذه السمة فهرس/موضع السلعة في القائمة.
item_brand string لا Google العلامة التجارية للسلعة
item_category string لا ملابس فئة السلعة إذا تم استخدامها كجزء من تسلسل هرمي للفئات أو تصنيف، ستكون هذه الفئة الأولى.
item_category2 string لا للبالغين التسلسل الهرمي للفئة الثانية أو التصنيف الإضافي للسلعة
item_category3 string لا قمصان التسلسل الهرمي للفئة الثالثة أو التصنيف الإضافي للسلعة
item_category4 string لا طاقم العمل التسلسل الهرمي للفئة الرابعة أو التصنيف الإضافي للسلعة
item_category5 string لا كُم قصير التسلسل الهرمي للفئة الخامسة أو التصنيف الإضافي للسلعة
item_list_id string لا related_products رقم تعريف القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_id على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_id على مستوى الحدث، في حال توفّرها.
item_list_name string لا المنتجات ذات الصلة اسم القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_name على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_name على مستوى الحدث، في حال توفّرها.
item_variant string لا أخضر صيغة العنصر أو رمز فريد أو وصف لمزيد من التفاصيل/خيارات العناصر
location_id string لا ChIJIQBpAG2ahYAR_6128GcTUEo (رقم تعريف المكان في Google لمدينة سان فرانسيسكو) الموقع الجغرافي المرتبط بالسلعة (مثل الموقع الجغرافي للمتجر). ننصحك باستخدام رقم تعريف المكان على Google الذي يتوافق مع العنصر المرتبط. ويمكن أيضًا استخدام معرّف موقع جغرافي مخصّص.
ملاحظة: لا يتوفّر location_id إلا على مستوى المنتج أو الخدمة.
بالإضافة إلى المَعلمات المحدّدة، يمكنك تضمين ما يصل إلى 27 مَعلمة مخصّصة في مصفوفة items.

مثال

يوضّح المثال التالي كيفية إرسال حدث begin_checkout باستخدام واجهة برمجة التطبيقات "إدارة بيانات إعلانات Google". في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "begin_checkout",
      "conversionValue": 30.03,
      "currency": "USD",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "cartData": {
        "couponCodes": [
          "SUMMER_FUN"
        ],
        "items": [
          {
            "itemId": "SKU_12345",
            "quantity": 1,
            "unitPrice": 29.99,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Triblend Android T-Shirt"
              }
            ]
          }
        ]
      }
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "begin_checkout",
      "params": {
        "currency": "USD",
        "value": 30.03,
        "coupon": "SUMMER_FUN",
        "items": [
          {
            "item_id": "SKU_12345",
            "item_name": "Stan and Friends Tee",
            "affiliation": "Google Merchandise Store",
            "coupon": "SUMMER_FUN",
            "currency": "USD",
            "discount": 2.22,
            "index": 0,
            "item_brand": "Google",
            "item_category": "Apparel",
            "item_category2": "Adult",
            "item_category3": "Shirts",
            "item_category4": "Crew",
            "item_category5": "Short sleeve",
            "item_list_id": "related_products",
            "item_list_name": "Related Products",
            "item_variant": "green",
            "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
            "price": 10.01,
            "google_business_vertical": "retail",
            "quantity": 3
          }
        ]
      }
    }]
  })
});

in_app_purchase

لا يتوفّر هذا الحدث إلا لمصادر بيانات التطبيقات.

استخدِم هذا الحدث عندما يُجري مستخدم عملية شراء داخل التطبيق.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة conversion_value الحدث، بتنسيق ISO 4217 المكوّن من 3 أحرف.

* في حال ضبط مَعلمة conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الأرباح بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث كحدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.
transaction_id string لا T_12345 المعرّف الفريد لمعاملة معيّنة

تساعدك المَعلمة transaction_id في تجنّب الحصول على أحداث مكرّرة لعملية شراء. اضبط الحقل transaction_id في العنصر Event.
cart_data.items Item[] لا السلع الخاصة بالحدث

اضبط الحقل cart_data.items في العنصر Event.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
product_id string لا ABC123456789 معرّف المنتج
subscription boolean لا صحيح

تشير إلى ما إذا كانت عملية الشراء عبارة عن اشتراك.
في حال عدم ضبط هذه السمة، يتم ضبطها تلقائيًا على false.
free_trial boolean لا صحيح

يشير إلى ما إذا كان الحدث مخصّصًا لفترة تجريبية مجانية من الاشتراك.
في حال عدم ضبط هذه السمة، يتم ضبطها تلقائيًا على false.
price_is_discounted boolean لا خطأ

يشير إلى ما إذا كان price يتضمّن خصمًا.
في حال عدم ضبط هذه السمة، يتم ضبطها تلقائيًا على false.

مثال

يوضّح المثال التالي كيفية إرسال حدث in_app_purchase باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "FIREBASE_APP_ID"
    }
  ],
  "events": [
    {
      "eventName": "in_app_purchase",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "APP",
      "appInstanceId": "APP_INSTANCE_ID",
      "currency": "USD",
      "transactionId": "T_12345",
      "conversionValue": 30.03,
      "cartData": {
        "items": [
          {
            "itemId": "ABC123456789",
            "quantity": 3,
            "unitPrice": 10.01
          }
        ]
      },
      "additionalEventParameters": [
        {
          "parameterName": "subscription",
          "value": true
        },
        {
          "parameterName": "free_trial",
          "value": false
        },
        {
          "parameterName": "price_is_discounted",
          "value": false
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "app_instance_id": "app_instance_id",
    "events":[{
      "name":"in_app_purchase",
      "params":{
        "currency": "USD",
        "value": 30.03,
        "quantity": 3,
        "transaction_id": "T_12345",
        "product_id": "ABC123456789",
        "subscription": true,
        "free_trial": false,
        "price_is_discounted": false
      }
    }]
  })
});

purchase

يشير هذا الحدث إلى شراء مستخدم لسلعة واحدة أو أكثر.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة السلع المرتبطة بالحدث، بتنسيق ISO 4217 المُكوَّن من 3 أحرف.

* لا تساهم مقاييس القيمة في الحدث view_item في الإيرادات

* في حال ضبط conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الإيرادات بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* اضبط conversion_value على مجموع (price * quantity) لجميع السلع في items. لا تُدرِج shipping أو tax.
* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث كحدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.
transaction_id string نعم T_12345 المعرّف الفريد لمعاملة معيّنة

تساعدك المَعلمة transaction_id في تجنّب الحصول على أحداث مكرّرة لعملية شراء. اضبط الحقل transaction_id في العنصر Event.
user_properties.customer_type CustomerType لا NEW ما إذا كانت الإحالة الناجحة من عميل NEW أو RETURNING.
cart_data.items Item[] نعم السلع الخاصة بالحدث

اضبط الحقل cart_data.items في العنصر Event.
cart_data.coupon_codes string[] لا SUMMER_FUN رمز القسيمة المرتبط بالحدث


اضبط الحقل coupon_codes في العنصر CartData.
* يجب تقديم رمز قسيمة واحد فقط في هذه القائمة.
* لا يرتبط هذا برمز القسيمة على مستوى السلعة.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
shipping number لا 3.33 تكلفة الشحن المرتبطة بمعاملة معيّنة
tax number لا 1.11 تكلفة الضريبة المرتبطة بالمعاملة

مَعلمات المنتج أو الخدمة

الاسم النوع مطلوب مثال على القيمة الوصف
item_name string نعم* قميص Stan and Friends

اسم السلعة.

*يجب توفير إما item_id أو item_name.

affiliation string لا Google Store ارتباط المنتج لتحديد الشركة التي تقدّمه أو الموقع الجغرافي للمتجر الذي يقدّمه
ملاحظة: لا يتوفّر affiliation إلا على مستوى المنتج أو الخدمة.
coupon string لا SUMMER_FUN اسم/رمز القسيمة المرتبط بالسلعة

تكون مَعلمات coupon على مستوى الحدث وعلى مستوى السلعة مستقلة.
discount number لا 2.22 قيمة الخصم النقدي للوحدة المرتبطة بالسلعة
index number لا 5 تمثّل هذه السمة فهرس/موضع السلعة في القائمة.
item_brand string لا Google العلامة التجارية للسلعة
item_category string لا ملابس فئة السلعة إذا تم استخدامها كجزء من تسلسل هرمي للفئات أو تصنيف، ستكون هذه الفئة الأولى.
item_category2 string لا للبالغين التسلسل الهرمي للفئة الثانية أو التصنيف الإضافي للسلعة
item_category3 string لا قمصان التسلسل الهرمي للفئة الثالثة أو التصنيف الإضافي للسلعة
item_category4 string لا طاقم العمل التسلسل الهرمي للفئة الرابعة أو التصنيف الإضافي للسلعة
item_category5 string لا كُم قصير التسلسل الهرمي للفئة الخامسة أو التصنيف الإضافي للسلعة
item_list_id string لا related_products رقم تعريف القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_id على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_id على مستوى الحدث، في حال توفّرها.
item_list_name string لا المنتجات ذات الصلة اسم القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_name على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_name على مستوى الحدث، في حال توفّرها.
item_variant string لا أخضر صيغة العنصر أو رمز فريد أو وصف لمزيد من التفاصيل/خيارات العناصر
location_id string لا ChIJIQBpAG2ahYAR_6128GcTUEo (رقم تعريف المكان في Google لمدينة سان فرانسيسكو) الموقع الجغرافي المرتبط بالسلعة (مثل الموقع الجغرافي للمتجر) ننصحك باستخدام رقم تعريف المكان على Google الذي يتوافق مع العنصر المرتبط. ويمكن أيضًا استخدام معرّف موقع جغرافي مخصّص.
ملاحظة: لا يتوفّر location_id إلا على مستوى المنتج أو الخدمة.
بالإضافة إلى المَعلمات المحدّدة، يمكنك تضمين ما يصل إلى 27 مَعلمة مخصّصة في مصفوفة items.

مثال

يوضّح المثال التالي كيفية إرسال حدث purchase باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "purchase",
      "transactionId": "TRANSACTION_ID",
      "conversionValue": 83.99,
      "currency": "USD",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "userProperties": {
        "customerType": "RETURNING"
      },
      "cartData": {
        "couponCodes": [
          "SUMMER_FUN"
        ],
        "items": [
          {
            "itemId": "SKU_12345",
            "quantity": 3,
            "unitPrice": 10.01,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Stan and Friends Tee"
              },
              {
                "parameterName": "affiliation",
                "value": "Google Merchandise Store"
              },
              {
                "parameterName": "discount",
                "value": "2.22"
              },
              {
                "parameterName": "index",
                "value": "0"
              },
              {
                "parameterName": "item_brand",
                "value": "Google"
              },
              {
                "parameterName": "item_category",
                "value": "Apparel"
              },
              {
                "parameterName": "item_category2",
                "value": "Adult"
              },
              {
                "parameterName": "item_category3",
                "value": "Shirts"
              },
              {
                "parameterName": "item_category4",
                "value": "Crew"
              },
              {
                "parameterName": "item_category5",
                "value": "Short sleeve"
              },
              {
                "parameterName": "item_list_id",
                "value": "related_products"
              },
              {
                "parameterName": "item_list_name",
                "value": "Related Products"
              },
              {
                "parameterName": "item_variant",
                "value": "green"
              },
              {
                "parameterName": "location_id",
                "value": "ChIJIQBpAG2ahYAR_6128GcTUEo"
              },
              {
                "parameterName": "google_business_vertical",
                "value": "retail"
              }
            ]
          }
        ]
      },
      "additionalEventParameters": [
        {
          "parameterName": "shipping",
          "value": "3.33"
        },
        {
          "parameterName": "tax",
          "value": "1.11"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
    method: "POST",
    body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "purchase",
      "params": {
        "currency": "USD",
        "transaction_id": "T_12345",
        "value": 30.03,
        "coupon": "SUMMER_FUN",
        "shipping": 3.33,
        "tax": 1.11,
        "items": [
            {
            "item_id": "SKU_12345",
            "item_name": "Stan and Friends Tee",
            "affiliation": "Google Merchandise Store",
            "coupon": "SUMMER_FUN",
            "currency": "USD",
            "discount": 2.22,
            "index": 0,
            "item_brand": "Google",
            "item_category": "Apparel",
            "item_category2": "Adult",
            "item_category3": "Shirts",
            "item_category4": "Crew",
            "item_category5": "Short sleeve",
            "item_list_id": "related_products",
            "item_list_name": "Related Products",
            "item_variant": "green",
            "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
            "price": 10.01,
            "google_business_vertical": "retail",
            "quantity": 3
          }
        ]
      }
    }]
  })
});

refund

يشير هذا الحدث إلى وقت ردّ الأموال المدفوعة مقابل سلعة واحدة أو أكثر إلى مستخدم.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة السلع المرتبطة بالحدث، بتنسيق ISO 4217 المُكوَّن من 3 أحرف.

* لا تساهم مقاييس القيمة في الحدث view_item في الإيرادات

* في حال ضبط conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الإيرادات بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* اضبط conversion_value على مجموع (price * quantity) لجميع العناصر في items. لا تُدرِج shipping أو tax.
* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث على أنّه حدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط السمة currency في حال ضبط السمة conversion_value.
transaction_id string نعم T_12345 المعرّف الفريد لمعاملة معيّنة
cart_data.items Item[] لا السلع الخاصة بالحدث

اضبط الحقل cart_data.items في العنصر Event.
cart_data.coupon_codes string[] لا SUMMER_FUN رمز القسيمة المرتبط بالحدث


اضبط الحقل coupon_codes في العنصر CartData.
* يجب تقديم رمز قسيمة واحد فقط في هذه القائمة.
* لا علاقة لذلك برموز القسائم على مستوى السلعة.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
shipping number لا 3.33 تكلفة الشحن المرتبطة بمعاملة معيّنة
tax number لا 1.11 تكلفة الضريبة المرتبطة بالمعاملة

مَعلمات المنتج أو الخدمة

الاسم النوع مطلوب مثال على القيمة الوصف
item_name string نعم* قميص Stan and Friends

اسم السلعة.

*يجب توفير إما item_id أو item_name.

affiliation string لا Google Store ارتباط المنتج لتحديد الشركة التي تقدّمه أو الموقع الجغرافي للمتجر الذي يقدّمه
ملاحظة: لا يتوفّر affiliation إلا على مستوى المنتج أو الخدمة.
coupon string لا SUMMER_FUN اسم/رمز القسيمة المرتبط بالسلعة

تكون مَعلمات coupon على مستوى الحدث وعلى مستوى السلعة مستقلة.
discount number لا 2.22 قيمة الخصم النقدي للوحدة المرتبطة بالسلعة
index number لا 5 تمثّل هذه السمة فهرس/موضع السلعة في القائمة.
item_brand string لا Google العلامة التجارية للسلعة
item_category string لا ملابس فئة السلعة إذا تم استخدامها كجزء من تسلسل هرمي للفئات أو تصنيف، ستكون هذه الفئة الأولى.
item_category2 string لا للبالغين التسلسل الهرمي للفئة الثانية أو التصنيف الإضافي للسلعة
item_category3 string لا قمصان التسلسل الهرمي للفئة الثالثة أو التصنيف الإضافي للسلعة
item_category4 string لا طاقم العمل التسلسل الهرمي للفئة الرابعة أو التصنيف الإضافي للسلعة
item_category5 string لا كُم قصير التسلسل الهرمي للفئة الخامسة أو التصنيف الإضافي للسلعة
item_list_id string لا related_products رقم تعريف القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_id على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_id على مستوى الحدث، في حال توفّرها.
item_list_name string لا المنتجات ذات الصلة اسم القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_name على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_name على مستوى الحدث، في حال توفّرها.
item_variant string لا أخضر صيغة العنصر أو رمز فريد أو وصف لمزيد من التفاصيل/خيارات العناصر
location_id string لا ChIJIQBpAG2ahYAR_6128GcTUEo (رقم تعريف المكان في Google لمدينة سان فرانسيسكو) الموقع الجغرافي المرتبط بالسلعة (مثل الموقع الجغرافي للمتجر). ننصحك باستخدام رقم تعريف المكان على Google الذي يتوافق مع العنصر المرتبط. ويمكن أيضًا استخدام معرّف موقع جغرافي مخصّص.
ملاحظة: لا تتوفّر السمة location_id إلا على مستوى المنتج أو الخدمة.
بالإضافة إلى المَعلمات المحدّدة، يمكنك تضمين ما يصل إلى 27 مَعلمة مخصّصة في مصفوفة items.

مثال

يوضّح المثال التالي كيفية إرسال حدث refund باستخدام واجهة برمجة التطبيقات "إدارة بيانات إعلانات Google". في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "refund",
      "conversionValue": 30.03,
      "currency": "USD",
      "transactionId": "T_12345",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "additionalEventParameters": [
        {
          "parameterName": "shipping",
          "value": 3.33
        },
        {
          "parameterName": "tax",
          "value": 1.11
        }
      ],
      "cartData": {
        "couponCodes": [
          "SUMMER_FUN"
        ],
        "items": [
          {
            "itemId": "SKU_12345",
            "quantity": 1,
            "unitPrice": 29.99,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Triblend Android T-Shirt"
              }
            ]
          }
        ]
      }
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "refund",
      "params": {
        "currency": "USD",
        "transaction_id": "T_12345",
        "value": 30.03,
        "coupon": "SUMMER_FUN",
        "shipping": 3.33,
        "tax": 1.11,
        "items": [
          {
            "item_id": "SKU_12345",
            "item_name": "Stan and Friends Tee",
            "affiliation": "Google Merchandise Store",
            "coupon": "SUMMER_FUN",
            "currency": "USD",
            "discount": 2.22,
            "index": 0,
            "item_brand": "Google",
            "item_category": "Apparel",
            "item_category2": "Adult",
            "item_category3": "Shirts",
            "item_category4": "Crew",
            "item_category5": "Short sleeve",
            "item_list_id": "related_products",
            "item_list_name": "Related Products",
            "item_variant": "green",
            "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
            "price": 10.01,
            "google_business_vertical": "retail",
            "quantity": 3
          }
        ]
      }
    }]
  })
});

remove_from_cart

يشير هذا الحدث إلى أنّه تمت إزالة سلعة من سلة تسوّق.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة السلع المرتبطة بالحدث، بتنسيق ISO 4217 المُكوَّن من 3 أحرف.

* لا تساهم مقاييس القيمة في الحدث view_item في الإيرادات

* في حال ضبط conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الإيرادات بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* اضبط conversion_value على مجموع (price * quantity) لجميع السلع في items. لا تُدرِج shipping أو tax.
* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث كحدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.
cart_data.items Item[] نعم السلع الخاصة بالحدث

اضبط الحقل cart_data.items في العنصر Event.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

مَعلمات المنتج أو الخدمة

الاسم النوع مطلوب مثال على القيمة الوصف
item_name string نعم* قميص Stan and Friends

اسم السلعة.

*يجب توفير إما item_id أو item_name.

affiliation string لا Google Store ارتباط المنتج لتحديد الشركة التي تقدّمه أو الموقع الجغرافي للمتجر الذي يقدّمه
ملاحظة: لا يتوفّر affiliation إلا على مستوى المنتج أو الخدمة.
coupon string لا SUMMER_FUN اسم/رمز القسيمة المرتبط بالسلعة

تكون مَعلمات coupon على مستوى الحدث وعلى مستوى السلعة مستقلة.
discount number لا 2.22 قيمة الخصم النقدي للوحدة المرتبطة بالسلعة
index number لا 5 تمثّل هذه السمة فهرس/موضع السلعة في القائمة.
item_brand string لا Google العلامة التجارية للسلعة
item_category string لا ملابس فئة السلعة إذا تم استخدامها كجزء من تسلسل هرمي للفئات أو تصنيف، ستكون هذه الفئة الأولى.
item_category2 string لا للبالغين التسلسل الهرمي للفئة الثانية أو التصنيف الإضافي للسلعة
item_category3 string لا قمصان التسلسل الهرمي للفئة الثالثة أو التصنيف الإضافي للسلعة
item_category4 string لا طاقم العمل التسلسل الهرمي للفئة الرابعة أو التصنيف الإضافي للسلعة
item_category5 string لا كُم قصير التسلسل الهرمي للفئة الخامسة أو التصنيف الإضافي للسلعة
item_list_id string لا related_products رقم تعريف القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_id على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_id على مستوى الحدث، في حال توفّرها.
item_list_name string لا المنتجات ذات الصلة اسم القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_name على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_name على مستوى الحدث، في حال توفّرها.
item_variant string لا أخضر صيغة العنصر أو رمز فريد أو وصف لمزيد من التفاصيل/خيارات العناصر
location_id string لا ChIJIQBpAG2ahYAR_6128GcTUEo (رقم تعريف المكان في Google لمدينة سان فرانسيسكو) الموقع الجغرافي المرتبط بالسلعة (مثل الموقع الجغرافي للمتجر). ننصحك باستخدام رقم تعريف المكان على Google الذي يتوافق مع العنصر المرتبط. ويمكن أيضًا استخدام معرّف موقع جغرافي مخصّص.
ملاحظة: لا تتوفّر السمة location_id إلا على مستوى المنتج أو الخدمة.
بالإضافة إلى المَعلمات المحدّدة، يمكنك تضمين ما يصل إلى 27 مَعلمة مخصّصة في مصفوفة items.

مثال

يوضّح المثال التالي كيفية إرسال حدث remove_from_cart باستخدام Data Manager API. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "remove_from_cart",
      "conversionValue": 30.03,
      "currency": "USD",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "cartData": {
        "items": [
          {
            "itemId": "SKU_12345",
            "quantity": 1,
            "unitPrice": 29.99,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Triblend Android T-Shirt"
              }
            ]
          }
        ]
      }
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "remove_from_cart",
      "params": {
        "currency": "USD",
        "value": 30.03,
        "items": [
          {
            "item_id": "SKU_12345",
            "item_name": "Stan and Friends Tee",
            "affiliation": "Google Merchandise Store",
            "coupon": "SUMMER_FUN",
            "currency": "USD",
            "discount": 2.22,
            "index": 0,
            "item_brand": "Google",
            "item_category": "Apparel",
            "item_category2": "Adult",
            "item_category3": "Shirts",
            "item_category4": "Crew",
            "item_category5": "Short sleeve",
            "item_list_id": "related_products",
            "item_list_name": "Related Products",
            "item_variant": "green",
            "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
            "price": 10.01,
            "google_business_vertical": "retail",
            "quantity": 3
          }
        ]
      }
    }]
  })
});

select_item

يشير هذا الحدث إلى أنّه تم اختيار سلعة من قائمة.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
cart_data.items Item[] نعم* السلع الخاصة بالحدث

* من المتوقّع أن تحتوي مصفوفة items على عنصر واحد يمثّل العنصر المحدّد. في حال تقديم عناصر متعددة، سيتم استخدام العنصر الأول فقط في items. ‫

اضبط الحقل cart_data.items على العنصر Event.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
item_list_id string لا related_products رقم تعريف القائمة التي تم فيها عرض السلعة للمستخدِم

يتم تجاهل هذه السمة إذا تم ضبطها على مستوى السلعة.
item_list_name string لا المنتجات ذات الصلة اسم القائمة التي تم فيها عرض السلعة للمستخدِم

يتم تجاهل هذه السمة إذا تم ضبطها على مستوى السلعة.

مَعلمات المنتج أو الخدمة

الاسم النوع مطلوب مثال على القيمة الوصف
item_name string نعم* قميص Stan and Friends

اسم السلعة.

*يجب توفير إما item_id أو item_name.

affiliation string لا Google Store ارتباط المنتج لتحديد الشركة التي تقدّمه أو الموقع الجغرافي للمتجر الذي يقدّمه
ملاحظة: لا يتوفّر affiliation إلا على مستوى المنتج أو الخدمة.
coupon string لا SUMMER_FUN اسم/رمز القسيمة المرتبط بالسلعة

تكون مَعلمات coupon على مستوى الحدث وعلى مستوى السلعة مستقلة.
discount number لا 2.22 قيمة الخصم النقدي للوحدة المرتبطة بالسلعة
index number لا 5 تمثّل هذه السمة فهرس/موضع السلعة في القائمة.
item_brand string لا Google العلامة التجارية للسلعة
item_category string لا ملابس فئة السلعة إذا تم استخدامها كجزء من تسلسل هرمي للفئات أو تصنيف، ستكون هذه الفئة الأولى.
item_category2 string لا للبالغين التسلسل الهرمي للفئة الثانية أو التصنيف الإضافي للسلعة
item_category3 string لا قمصان التسلسل الهرمي للفئة الثالثة أو التصنيف الإضافي للسلعة
item_category4 string لا طاقم العمل التسلسل الهرمي للفئة الرابعة أو التصنيف الإضافي للسلعة
item_category5 string لا كُم قصير التسلسل الهرمي للفئة الخامسة أو التصنيف الإضافي للسلعة
item_list_id string لا related_products رقم تعريف القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_id على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_id على مستوى الحدث، في حال توفّرها.
item_list_name string لا المنتجات ذات الصلة اسم القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_name على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_name على مستوى الحدث، في حال توفّرها.
item_variant string لا أخضر صيغة العنصر أو رمز فريد أو وصف لمزيد من التفاصيل/خيارات العناصر
location_id string لا ChIJIQBpAG2ahYAR_6128GcTUEo (رقم تعريف المكان في Google لمدينة سان فرانسيسكو) الموقع الجغرافي المرتبط بالسلعة (مثل الموقع الجغرافي للمتجر). ننصحك باستخدام رقم تعريف المكان على Google الذي يتوافق مع العنصر المرتبط. ويمكن أيضًا استخدام معرّف موقع جغرافي مخصّص.
ملاحظة: لا تتوفّر السمة location_id إلا على مستوى المنتج أو الخدمة.
بالإضافة إلى المَعلمات المحدّدة، يمكنك تضمين ما يصل إلى 27 مَعلمة مخصّصة في مصفوفة items.

مثال

يوضّح المثال التالي كيفية إرسال حدث select_item باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "select_item",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "additionalEventParameters": [
        {
          "parameterName": "item_list_id",
          "value": "related_products"
        },
        {
          "parameterName": "item_list_name",
          "value": "Related products"
        }
      ],
      "cartData": {
        "items": [
          {
            "itemId": "SKU_12345",
            "quantity": 1,
            "unitPrice": 29.99,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Triblend Android T-Shirt"
              }
            ]
          }
        ]
      }
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "select_item",
      "params": {
        "item_list_id": "related_products",
        "item_list_name": "Related products",
        "items": [
          {
            "item_id": "SKU_12345",
            "item_name": "Stan and Friends Tee",
            "affiliation": "Google Merchandise Store",
            "coupon": "SUMMER_FUN",
            "currency": "USD",
            "discount": 2.22,
            "index": 0,
            "item_brand": "Google",
            "item_category": "Apparel",
            "item_category2": "Adult",
            "item_category3": "Shirts",
            "item_category4": "Crew",
            "item_category5": "Short sleeve",
            "item_list_id": "related_products",
            "item_list_name": "Related Products",
            "item_variant": "green",
            "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
            "price": 10.01,
            "google_business_vertical": "retail",
            "quantity": 3
          }
        ]
      }
    }]
  })
});

select_promotion

يشير هذا الحدث إلى أنّه تم اختيار عرض ترويجي من قائمة.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
cart_data.items Item[] لا السلع الخاصة بالحدث

اضبط الحقل cart_data.items على العنصر Event.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
creative_name string لا summer_banner2 اسم تصميم الإعلان الترويجي
creative_slot string لا featured_app_1 اسم خانة تصميم الإعلان الترويجي المرتبط بالحدث.
promotion_id string لا P_12345 رقم تعريف العرض الترويجي المرتبط بالحدث
promotion_name string لا تخفيضات الصيف اسم العرض الترويجي المرتبط بالحدث

مَعلمات المنتج أو الخدمة

الاسم النوع مطلوب مثال على القيمة الوصف
item_name string نعم* قميص Stan and Friends

اسم السلعة.

*يجب توفير إما item_id أو item_name.

affiliation string لا Google Store ارتباط المنتج لتحديد الشركة التي تقدّمه أو الموقع الجغرافي للمتجر الذي يقدّمه
ملاحظة: لا يتوفّر affiliation إلا على مستوى المنتج أو الخدمة.
coupon string لا SUMMER_FUN اسم/رمز القسيمة المرتبط بالسلعة

تكون مَعلمات coupon على مستوى الحدث وعلى مستوى السلعة مستقلة.
creative_name string لا summer_banner2 اسم تصميم الإعلان الترويجي

يتم ضبط القيمة التلقائية على مستوى الحدث creative_name في حال عدم تحديدها.
creative_slot string لا featured_app_1 اسم خانة تصميم الإعلان الترويجي المرتبط بالسلعة

يتم ضبط القيمة التلقائية على مستوى الحدث creative_slot في حال عدم تحديدها.
discount number لا 2.22 قيمة الخصم النقدي للوحدة المرتبطة بالسلعة
index number لا 5 تمثّل هذه السمة فهرس/موضع السلعة في القائمة.
item_brand string لا Google العلامة التجارية للسلعة
item_category string لا ملابس فئة السلعة إذا تم استخدامها كجزء من تسلسل هرمي للفئات أو تصنيف، ستكون هذه الفئة الأولى.
item_category2 string لا للبالغين التسلسل الهرمي للفئة الثانية أو التصنيف الإضافي للسلعة
item_category3 string لا قمصان التسلسل الهرمي للفئة الثالثة أو التصنيف الإضافي للسلعة
item_category4 string لا طاقم العمل التسلسل الهرمي للفئة الرابعة أو التصنيف الإضافي للسلعة
item_category5 string لا كُم قصير التسلسل الهرمي للفئة الخامسة أو التصنيف الإضافي للسلعة
item_list_id string لا related_products رقم تعريف القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_id على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_id على مستوى الحدث، في حال توفّرها.
item_list_name string لا المنتجات ذات الصلة اسم القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_name على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_name على مستوى الحدث، في حال توفّرها.
item_variant string لا أخضر صيغة العنصر أو رمز فريد أو وصف لمزيد من التفاصيل/خيارات العناصر
location_id string لا ChIJIQBpAG2ahYAR_6128GcTUEo (رقم تعريف المكان في Google لمدينة سان فرانسيسكو) الموقع الجغرافي المرتبط بالسلعة (مثل الموقع الجغرافي للمتجر). ننصحك باستخدام رقم تعريف المكان على Google الذي يتوافق مع العنصر المرتبط. ويمكن أيضًا استخدام معرّف موقع جغرافي مخصّص.
ملاحظة: لا تتوفّر السمة location_id إلا على مستوى المنتج أو الخدمة.
promotion_id string لا P_12345 معرّف العرض الترويجي المرتبط بالسلعة

يتم ضبط القيمة التلقائية على مستوى الحدث promotion_id في حال عدم تحديدها.
promotion_name string لا تخفيضات الصيف اسم العرض الترويجي المرتبط بالسلعة

يتم ضبط القيمة التلقائية على مستوى الحدث promotion_name في حال عدم تحديدها.
بالإضافة إلى المَعلمات المحدّدة، يمكنك تضمين ما يصل إلى 27 مَعلمة مخصّصة في مصفوفة items.

مثال

يوضّح المثال التالي كيفية إرسال حدث select_promotion باستخدام Data Manager API. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "select_promotion",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "additionalEventParameters": [
        {
          "parameterName": "creative_name",
          "value": "Summer Banner"
        },
        {
          "parameterName": "creative_slot",
          "value": "featured_app_1"
        },
        {
          "parameterName": "promotion_id",
          "value": "P_12345"
        },
        {
          "parameterName": "promotion_name",
          "value": "Summer Sale"
        }
      ],
      "cartData": {
        "items": [
          {
            "itemId": "SKU_12345",
            "quantity": 1,
            "unitPrice": 29.99,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Triblend Android T-Shirt"
              }
            ]
          }
        ]
      }
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "select_promotion",
      "params": {
        "creative_name": "Summer Banner",
        "creative_slot": "featured_app_1",
        "promotion_id": "P_12345",
        "promotion_name": "Summer Sale",
        "items": [
          {
            "item_id": "SKU_12345",
            "item_name": "Stan and Friends Tee",
            "affiliation": "Google Merchandise Store",
            "coupon": "SUMMER_FUN",
            "creative_name": "summer_banner2",
            "creative_slot": "featured_app_1",
            "currency": "USD",
            "discount": 2.22,
            "index": 0,
            "item_brand": "Google",
            "item_category": "Apparel",
            "item_category2": "Adult",
            "item_category3": "Shirts",
            "item_category4": "Crew",
            "item_category5": "Short sleeve",
            "item_list_id": "related_products",
            "item_list_name": "Related Products",
            "item_variant": "green",
            "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
            "price": 10.01,
            "promotion_id": "P_12345",
            "promotion_name": "Summer Sale",
            "google_business_vertical": "retail",
            "quantity": 3
          }
        ]
      }
    }]
  })
});

view_cart

يشير هذا الحدث إلى أنّ المستخدم قد اطّلع على سلة التسوّق.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة السلع المرتبطة بالحدث، بتنسيق ISO 4217 المُكوَّن من 3 أحرف.

* لا تساهم مقاييس القيمة في الحدث view_item في الإيرادات

* في حال ضبط مَعلمة conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الإيرادات بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* اضبط conversion_value على مجموع (price * quantity) لجميع العناصر في items. لا تُدرِج shipping أو tax.
* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث كحدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط السمة currency في حال ضبط السمة conversion_value.
cart_data.items Item[] نعم السلع الخاصة بالحدث

اضبط الحقل cart_data.items في العنصر Event.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

مَعلمات المنتج أو الخدمة

الاسم النوع مطلوب مثال على القيمة الوصف
item_name string نعم* قميص Stan and Friends

اسم السلعة.

*يجب توفير إما item_id أو item_name.

affiliation string لا Google Store ارتباط المنتج لتحديد الشركة التي تقدّمه أو الموقع الجغرافي للمتجر الذي يقدّمه
ملاحظة: لا يتوفّر affiliation إلا على مستوى المنتج أو الخدمة.
coupon string لا SUMMER_FUN اسم/رمز القسيمة المرتبط بالسلعة

تكون مَعلمات coupon على مستوى الحدث وعلى مستوى السلعة مستقلة.
discount number لا 2.22 قيمة الخصم النقدي للوحدة المرتبطة بالسلعة
index number لا 5 تمثّل هذه السمة فهرس/موضع السلعة في القائمة.
item_brand string لا Google العلامة التجارية للسلعة
item_category string لا ملابس فئة السلعة إذا تم استخدامها كجزء من تسلسل هرمي للفئات أو تصنيف، ستكون هذه الفئة الأولى.
item_category2 string لا للبالغين التسلسل الهرمي للفئة الثانية أو التصنيف الإضافي للسلعة
item_category3 string لا قمصان التسلسل الهرمي للفئة الثالثة أو التصنيف الإضافي للسلعة
item_category4 string لا طاقم العمل التسلسل الهرمي للفئة الرابعة أو التصنيف الإضافي للسلعة
item_category5 string لا كُم قصير التسلسل الهرمي للفئة الخامسة أو التصنيف الإضافي للسلعة
item_list_id string لا related_products رقم تعريف القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_id على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_id على مستوى الحدث، في حال توفّرها.
item_list_name string لا المنتجات ذات الصلة اسم القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_name على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_name على مستوى الحدث، في حال توفّرها.
item_variant string لا أخضر صيغة العنصر أو رمز فريد أو وصف لمزيد من التفاصيل/خيارات العناصر
location_id string لا ChIJIQBpAG2ahYAR_6128GcTUEo (رقم تعريف المكان في Google لمدينة سان فرانسيسكو) الموقع الجغرافي المرتبط بالسلعة (مثل الموقع الجغرافي للمتجر). ننصحك باستخدام رقم تعريف المكان على Google الذي يتوافق مع العنصر المرتبط. ويمكن أيضًا استخدام معرّف موقع جغرافي مخصّص.
ملاحظة: لا تتوفّر السمة location_id إلا على مستوى المنتج أو الخدمة.
بالإضافة إلى المَعلمات المحدّدة، يمكنك تضمين ما يصل إلى 27 مَعلمة مخصّصة في مصفوفة items.

مثال

يوضّح المثال التالي كيفية إرسال حدث view_cart باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "view_cart",
      "conversionValue": 7.77,
      "currency": "USD",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "cartData": {
        "items": [
          {
            "itemId": "SKU_12345",
            "quantity": 1,
            "unitPrice": 29.99,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Triblend Android T-Shirt"
              }
            ]
          },
          {
            "itemId": "SKU_67890",
            "quantity": 2,
            "unitPrice": 24.00,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Google Red Team Hat"
              }
            ]
          }
        ]
      }
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "view_cart",
      "params": {
        "currency": "USD",
        "value": 7.77,
        "items": [
          {
            "item_id": "SKU_12345",
            "item_name": "Stan and Friends Tee",
            "affiliation": "Google Merchandise Store",
            "coupon": "SUMMER_FUN",
            "currency": "USD",
            "discount": 2.22,
            "index": 0,
            "item_brand": "Google",
            "item_category": "Apparel",
            "item_category2": "Adult",
            "item_category3": "Shirts",
            "item_category4": "Crew",
            "item_category5": "Short sleeve",
            "item_list_id": "related_products",
            "item_list_name": "Related Products",
            "item_variant": "green",
            "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
            "price": 10.01,
            "google_business_vertical": "retail",
            "quantity": 3
          }
        ]
      }
    }]
  })
});

view_item

يشير هذا الحدث إلى أنّه تم عرض بعض المحتوى للمستخدم. استخدِم هذا الحدث لمعرفة السلع الأكثر رواجًا التي تم الاطّلاع عليها.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة السلع المرتبطة بالحدث، بتنسيق ISO 4217 المُكوَّن من 3 أحرف.

* لا تساهم مقاييس القيمة في الحدث view_item في الإيرادات

* في حال ضبط conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الإيرادات بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* اضبط conversion_value على مجموع (price * quantity) لجميع العناصر في items. لا تُدرِج shipping أو tax.
* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث على أنّه حدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.
cart_data.items Item[] نعم السلع الخاصة بالحدث

اضبط الحقل cart_data.items في العنصر Event.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

مَعلمات المنتج أو الخدمة

الاسم النوع مطلوب مثال على القيمة الوصف
item_name string نعم* قميص Stan and Friends

اسم السلعة.

*يجب توفير إما item_id أو item_name.

affiliation string لا Google Store ارتباط المنتج لتحديد الشركة التي تقدّمه أو الموقع الجغرافي للمتجر الذي يقدّمه
ملاحظة: لا يتوفّر affiliation إلا على مستوى المنتج أو الخدمة.
coupon string لا SUMMER_FUN اسم/رمز القسيمة المرتبط بالسلعة

تكون مَعلمات coupon على مستوى الحدث وعلى مستوى السلعة مستقلة.
discount number لا 2.22 قيمة الخصم النقدي للوحدة المرتبطة بالسلعة
index number لا 5 تمثّل هذه السمة فهرس/موضع السلعة في القائمة.
item_brand string لا Google العلامة التجارية للسلعة
item_category string لا ملابس فئة السلعة إذا تم استخدامها كجزء من تسلسل هرمي للفئات أو تصنيف، ستكون هذه الفئة الأولى.
item_category2 string لا للبالغين التسلسل الهرمي للفئة الثانية أو التصنيف الإضافي للسلعة
item_category3 string لا قمصان التسلسل الهرمي للفئة الثالثة أو التصنيف الإضافي للسلعة
item_category4 string لا طاقم العمل التسلسل الهرمي للفئة الرابعة أو التصنيف الإضافي للسلعة
item_category5 string لا كُم قصير التسلسل الهرمي للفئة الخامسة أو التصنيف الإضافي للسلعة
item_list_id string لا related_products رقم تعريف القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_id على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_id على مستوى الحدث، في حال توفّرها.
item_list_name string لا المنتجات ذات الصلة اسم القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_name على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_name على مستوى الحدث، في حال توفّرها.
item_variant string لا أخضر صيغة العنصر أو رمز فريد أو وصف لمزيد من التفاصيل/خيارات العناصر
location_id string لا ChIJIQBpAG2ahYAR_6128GcTUEo (رقم تعريف المكان في Google لمدينة سان فرانسيسكو) الموقع الجغرافي المرتبط بالسلعة (مثل الموقع الجغرافي للمتجر). ننصحك باستخدام رقم تعريف المكان على Google الذي يتوافق مع العنصر المرتبط. ويمكن أيضًا استخدام معرّف موقع جغرافي مخصّص.
ملاحظة: لا يتوفّر location_id إلا على مستوى المنتج أو الخدمة.
بالإضافة إلى المَعلمات المحدّدة، يمكنك تضمين ما يصل إلى 27 مَعلمة مخصّصة في مصفوفة items.

مثال

يوضّح المثال التالي كيفية إرسال حدث view_item باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "view_item",
      "conversionValue": 7.77,
      "currency": "USD",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "cartData": {
        "items": [
          {
            "itemId": "SKU_12345",
            "quantity": 1,
            "unitPrice": 29.99,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Triblend Android T-Shirt"
              }
            ]
          },
          {
            "itemId": "SKU_67890",
            "quantity": 2,
            "unitPrice": 24.00,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Google Red Team Hat"
              }
            ]
          }
        ]
      }
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "view_item",
      "params": {
        "currency": "USD",
        "value": 7.77,
        "items": [
          {
            "item_id": "SKU_12345",
            "item_name": "Stan and Friends Tee",
            "affiliation": "Google Merchandise Store",
            "coupon": "SUMMER_FUN",
            "currency": "USD",
            "discount": 2.22,
            "index": 0,
            "item_brand": "Google",
            "item_category": "Apparel",
            "item_category2": "Adult",
            "item_category3": "Shirts",
            "item_category4": "Crew",
            "item_category5": "Short sleeve",
            "item_list_id": "related_products",
            "item_list_name": "Related Products",
            "item_variant": "green",
            "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
            "price": 10.01,
            "google_business_vertical": "retail",
            "quantity": 3
          }
        ],
      }
    }]
  })
});

view_item_list

سجِّل هذا الحدث عندما تظهر للمستخدم قائمة بالسلع من فئة معيّنة.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة السلع المرتبطة بالحدث، بتنسيق ISO 4217 المُكوَّن من 3 أحرف.

* لا تساهم مقاييس القيمة في الحدث view_item في الإيرادات

* في حال ضبط conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الإيرادات بدقة.
cart_data.items Item[] نعم السلع الخاصة بالحدث

اضبط الحقل cart_data.items على العنصر Event.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

مَعلمات المنتج أو الخدمة

الاسم النوع مطلوب مثال على القيمة الوصف
item_name string نعم* قميص Stan and Friends

اسم السلعة.

*يجب توفير إما item_id أو item_name.

affiliation string لا Google Store ارتباط المنتج لتحديد الشركة التي تقدّمه أو الموقع الجغرافي للمتجر الذي يقدّمه
ملاحظة: لا يتوفّر affiliation إلا على مستوى المنتج أو الخدمة.
coupon string لا SUMMER_FUN اسم/رمز القسيمة المرتبط بالسلعة

تكون مَعلمات coupon على مستوى الحدث وعلى مستوى السلعة مستقلة.
discount number لا 2.22 قيمة الخصم النقدي للوحدة المرتبطة بالسلعة
index number لا 5 تمثّل هذه السمة فهرس/موضع السلعة في القائمة.
item_brand string لا Google العلامة التجارية للسلعة
item_category string لا ملابس فئة السلعة إذا تم استخدامها كجزء من تسلسل هرمي للفئات أو تصنيف، ستكون هذه الفئة الأولى.
item_category2 string لا للبالغين التسلسل الهرمي للفئة الثانية أو التصنيف الإضافي للسلعة
item_category3 string لا قمصان التسلسل الهرمي للفئة الثالثة أو التصنيف الإضافي للسلعة
item_category4 string لا طاقم العمل التسلسل الهرمي للفئة الرابعة أو التصنيف الإضافي للسلعة
item_category5 string لا كُم قصير التسلسل الهرمي للفئة الخامسة أو التصنيف الإضافي للسلعة
item_list_id string لا related_products رقم تعريف القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_id على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_id على مستوى الحدث، في حال توفّرها.
item_list_name string لا المنتجات ذات الصلة اسم القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_name على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_name على مستوى الحدث، في حال توفّرها.
item_variant string لا أخضر صيغة العنصر أو رمز فريد أو وصف لمزيد من التفاصيل/خيارات العناصر
location_id string لا ChIJIQBpAG2ahYAR_6128GcTUEo (رقم تعريف المكان في Google لمدينة سان فرانسيسكو) الموقع الجغرافي المرتبط بالسلعة (مثل الموقع الجغرافي للمتجر). ننصحك باستخدام رقم تعريف المكان على Google الذي يتوافق مع العنصر المرتبط. ويمكن أيضًا استخدام معرّف موقع جغرافي مخصّص.
ملاحظة: لا تتوفّر السمة location_id إلا على مستوى المنتج أو الخدمة.
بالإضافة إلى المَعلمات المحدّدة، يمكنك تضمين ما يصل إلى 27 مَعلمة مخصّصة في مصفوفة items.

مثال

يوضّح المثال التالي كيفية إرسال حدث view_item_list باستخدام واجهة برمجة التطبيقات "إدارة بيانات إعلانات Google". في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "view_item_list",
      "currency": "USD",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "additionalEventParameters": [
        {
          "parameterName": "item_list_id",
          "value": "related_products"
        },
        {
          "parameterName": "item_list_name",
          "value": "Related products"
        }
      ],
      "cartData": {
        "items": [
          {
            "itemId": "SKU_12345",
            "quantity": 1,
            "unitPrice": 29.99,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Triblend Android T-Shirt"
              }
            ]
          }
        ]
      }
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "view_item_list",
      "params": {
        "item_list_id": "related_products",
        "item_list_name": "Related products",
        "items": [
          {
            "item_id": "SKU_12345",
            "item_name": "Stan and Friends Tee",
            "affiliation": "Google Merchandise Store",
            "coupon": "SUMMER_FUN",
            "currency": "USD",
            "discount": 2.22,
            "index": 0,
            "item_brand": "Google",
            "item_category": "Apparel",
            "item_category2": "Adult",
            "item_category3": "Shirts",
            "item_category4": "Crew",
            "item_category5": "Short sleeve",
            "item_list_id": "related_products",
            "item_list_name": "Related Products",
            "item_variant": "green",
            "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
            "price": 10.01,
            "google_business_vertical": "retail",
            "quantity": 3
          }
        ]
      }
    }]
  })
});

view_promotion

يشير هذا الحدث إلى أنّه تمّ عرض عرض ترويجي من قائمة.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
cart_data.items Item[] نعم* السلع الخاصة بالحدث

* من المتوقّع أن تحتوي مصفوفة items على عنصر واحد يمثّل السلعة المرتبطة بالعرض الترويجي. في حال تقديم عناصر متعددة، سيتم استخدام العنصر الأول فقط في items.

اضبط حقل cart_data.items في عنصر Event.

حقول المنتجات

الاسم النوع مطلوب مثال على القيمة الوصف
item_id string نعم I_12345 معرّف فريد للسلعة اضبط الحقل item_id في العنصر Item.
unit_price number نعم 27.67 سعر الوحدة باستثناء الضرائب والشحن والخصومات على مستوى الحدث (على مستوى المعاملة) لهذه السلعة.

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفَّض. على سبيل المثال، إذا كان سعر الوحدة لسلعة معيّنة هو 27.67 والخصم على الوحدة هو 6.66، اضبط قيمة unitPrice على 21.01.
quantity number نعم 1 عدد الوحدات التي تم شراؤها لهذه السلعة المحدّدة

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
creative_name string لا summer_banner2 اسم تصميم الإعلان الترويجي
creative_slot string لا featured_app_1 اسم خانة تصميم الإعلان الترويجي المرتبط بالحدث.
promotion_id string لا P_12345 رقم تعريف العرض الترويجي المرتبط بالحدث
promotion_name string لا تخفيضات الصيف اسم العرض الترويجي المرتبط بالحدث

مَعلمات المنتج أو الخدمة

الاسم النوع مطلوب مثال على القيمة الوصف
item_name string نعم* قميص Stan and Friends

اسم السلعة.

*يجب توفير إما item_id أو item_name.

affiliation string لا Google Store ارتباط المنتج لتحديد الشركة التي تقدّمه أو الموقع الجغرافي للمتجر الذي يقدّمه
ملاحظة: لا يتوفّر affiliation إلا على مستوى المنتج أو الخدمة.
coupon string لا SUMMER_FUN اسم/رمز القسيمة المرتبط بالسلعة

تكون مَعلمات coupon على مستوى الحدث وعلى مستوى السلعة مستقلة.
creative_name string لا summer_banner2 اسم تصميم الإعلان الترويجي

يتم ضبط القيمة التلقائية على مستوى الحدث creative_name في حال عدم تحديدها.
creative_slot string لا featured_app_1 اسم خانة تصميم الإعلان الترويجي المرتبط بالسلعة

يتم ضبط القيمة التلقائية على مستوى الحدث creative_slot في حال عدم تحديدها.
discount number لا 2.22 قيمة الخصم النقدي للوحدة المرتبطة بالسلعة
index number لا 5 تمثّل هذه السمة فهرس/موضع السلعة في القائمة.
item_brand string لا Google العلامة التجارية للسلعة
item_category string لا ملابس فئة السلعة إذا تم استخدامها كجزء من تسلسل هرمي للفئات أو تصنيف، ستكون هذه الفئة الأولى.
item_category2 string لا للبالغين التسلسل الهرمي للفئة الثانية أو التصنيف الإضافي للسلعة
item_category3 string لا قمصان التسلسل الهرمي للفئة الثالثة أو التصنيف الإضافي للسلعة
item_category4 string لا طاقم العمل التسلسل الهرمي للفئة الرابعة أو التصنيف الإضافي للسلعة
item_category5 string لا كُم قصير التسلسل الهرمي للفئة الخامسة أو التصنيف الإضافي للسلعة
item_list_id string لا related_products رقم تعريف القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_id على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_id على مستوى الحدث، في حال توفّرها.
item_list_name string لا المنتجات ذات الصلة اسم القائمة التي تم فيها عرض السلعة للمستخدِم

في حال ضبط هذه المَعلمة، يتم تجاهل المَعلمة item_list_name على مستوى الحدث.
في حال عدم ضبط هذه السمة، يتم استخدام السمة item_list_name على مستوى الحدث، في حال توفّرها.
item_variant string لا أخضر صيغة العنصر أو رمز فريد أو وصف لمزيد من التفاصيل/خيارات العناصر
location_id string لا ChIJIQBpAG2ahYAR_6128GcTUEo (رقم تعريف المكان في Google لمدينة سان فرانسيسكو) الموقع الجغرافي المرتبط بالسلعة (مثل الموقع الجغرافي للمتجر). ننصحك باستخدام رقم تعريف المكان على Google الذي يتوافق مع العنصر المرتبط. ويمكن أيضًا استخدام معرّف موقع جغرافي مخصّص.
ملاحظة: لا تتوفّر السمة location_id إلا على مستوى المنتج أو الخدمة.
promotion_id string لا P_12345 معرّف العرض الترويجي المرتبط بالسلعة

يتم ضبط القيمة التلقائية على مستوى الحدث promotion_id في حال عدم تحديدها.
promotion_name string لا تخفيضات الصيف اسم العرض الترويجي المرتبط بالسلعة

يتم ضبط القيمة التلقائية على مستوى الحدث promotion_name في حال عدم تحديدها.
بالإضافة إلى المَعلمات المحدّدة، يمكنك تضمين ما يصل إلى 27 مَعلمة مخصّصة في مصفوفة items.

مثال

يوضّح المثال التالي كيفية إرسال حدث view_promotion باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "view_promotion",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "userId": "USER_ID",
      "additionalEventParameters": [
        {
          "parameterName": "creative_name",
          "value": "Summer Banner"
        },
        {
          "parameterName": "creative_slot",
          "value": "featured_app_1"
        },
        {
          "parameterName": "promotion_id",
          "value": "P_12345"
        },
        {
          "parameterName": "promotion_name",
          "value": "Summer Sale"
        }
      ],
      "cartData": {
        "items": [
          {
            "itemId": "SKU_12345",
            "quantity": 1,
            "unitPrice": 29.99,
            "additionalItemParameters": [
              {
                "parameterName": "item_name",
                "value": "Triblend Android T-Shirt"
              }
            ]
          }
        ]
      }
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "view_promotion",
      "params": {
        "creative_name": "Summer Banner",
        "creative_slot": "featured_app_1",
        "promotion_id": "P_12345",
        "promotion_name": "Summer Sale",
        "items": [
          {
            "item_id": "SKU_12345",
            "item_name": "Stan and Friends Tee",
            "affiliation": "Google Merchandise Store",
            "coupon": "SUMMER_FUN",
            "creative_name": "summer_banner2",
            "creative_slot": "featured_app_1",
            "currency": "USD",
            "discount": 2.22,
            "index": 0,
            "item_brand": "Google",
            "item_category": "Apparel",
            "item_category2": "Adult",
            "item_category3": "Shirts",
            "item_category4": "Crew",
            "item_category5": "Short sleeve",
            "item_list_id": "related_products",
            "item_list_name": "Related Products",
            "item_variant": "green",
            "location_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
            "price": 10.01,
            "promotion_id": "P_12345",
            "promotion_name": "Summer Sale",
            "google_business_vertical": "retail",
            "quantity": 3
          }
        ]
      }
    }]
  })
});

الألعاب

level_up

يشير هذا الحدث إلى أنّ اللاعب قد انتقل إلى مستوى أعلى في اللعبة. ويمكنك استخدام هذا التقرير لقياس توزيع المستويات في قاعدة المستخدمين وتحديد المستويات التي يصعب إكمالها.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
level number لا 5 مستوى الشخصية
character string لا اللاعب 1 الشخصية التي انتقلت إلى مستوى أعلى

مثال

يوضّح المثال التالي كيفية إرسال حدث level_up باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "level_up",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "additionalEventParameters": [
        {
          "parameterName": "level",
          "value": 5
        },
        {
          "parameterName": "character",
          "value": "Player 1"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "level_up",
      "params": {
        "level": 5,
        "character": "Player 1"
      }
    }]
  })
});

post_score

أرسِل هذا الحدث عندما ينشر المستخدم نتيجة. استخدِم هذا الحدث لفهم مستوى أداء المستخدمين في لعبتك وربط أعلى النتائج بشرائح الجمهور أو السلوكيات.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
score number نعم 10000 النتيجة المطلوب نشرها
level number لا 5 مستوى النتيجة
character string لا اللاعب 1 الشخصية التي حقّقت النتيجة

مثال

يوضّح المثال التالي كيفية إرسال حدث post_score باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "post_score",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "additionalEventParameters": [
        {
          "parameterName": "score",
          "value": 10000
        },
        {
          "parameterName": "level",
          "value": 5
        },
        {
          "parameterName": "character",
          "value": "Player 1"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "post_score",
      "params": {
        "score": 10000,
        "level": 5,
        "character": "Player 1"
      }
    }]
  })
});

unlock_achievement

سجِّل هذا الحدث عندما يفتح المستخدم إنجازًا. يمكن أن يساعدك هذا الحدث في فهم كيفية تجربة المستخدمين للعبتك.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
achievement_id string نعم A_12345 رقم تعريف الإنجاز الذي تم فتحه.

مثال

يوضّح المثال التالي كيفية إرسال حدث unlock_achievement باستخدام Data Manager API. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "unlock_achievement",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "additionalEventParameters": [
        {
          "parameterName": "achievement_id",
          "value": "A_12345"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "unlock_achievement",
      "params": {
        "achievement_id": "A_12345"
      }
    }]
  })
});

إنشاء قوائم العملاء المحتملِين

close_convert_lead

سجِّل هذا الحدث عندما يتم تحويل عميل محتمل مؤهَّل بنجاح إلى عميل. يشير ذلك عادةً إلى نهاية عملية تعزيز اهتمام العملاء المحتملين، مثلاً عند توقيع عقد أو بدء اشتراك مدفوع أو إتمام عملية بيع نهائية.

  • ملاحظة: لتتبُّع اكتساب العملاء المحتملين الأوّلي، مثل عمليات إرسال النماذج أو الاشتراك في النشرات الإخبارية أو طلبات العروض التوضيحية، استخدِم الحدث generate_lead.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة conversion_value الحدث، بتنسيق ISO 4217 المكوّن من 3 أحرف.

* في حال ضبط مَعلمة conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الأرباح بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث على أنّه حدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.

مثال

يوضّح المثال التالي كيفية إرسال حدث close_convert_lead باستخدام Data Manager API. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "close_convert_lead",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "currency": "USD",
      "conversionValue": 30.03
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "close_convert_lead",
      "params": {
        "currency": "USD",
        "value": 30.03
      }
    }]
  })
});

close_unconvert_lead

يقيس هذا الحدث الحالات التي يتم فيها تحديد أنّ المستخدم لن يصبح عميلاً محتملاً أجرى إحالة ناجحة، مع ذكر السبب.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة conversion_value الحدث، بتنسيق ISO 4217 المكوّن من 3 أحرف

* في حال ضبط مَعلمة conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الأرباح بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث كحدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
unconvert_lead_reason string لا لم يتم الرد مطلقًا يشير ذلك إلى سبب عدم إجراء العميل المحتمل لإحالة ناجحة.

مثال

يوضّح المثال التالي كيفية إرسال حدث close_unconvert_lead باستخدام Data Manager API. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "close_unconvert_lead",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "currency": "USD",
      "conversionValue": 30.03,
      "additionalEventParameters": [
        {
          "parameterName": "unconvert_lead_reason",
          "value": "Never responded"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "close_unconvert_lead",
      "params": {
        "currency": "USD",
        "value": 30.03,
        "unconvert_lead_reason": "Never responded"
      }
    }]
  })
});

disqualify_lead

يقيس هذا الحدث الحالات التي يتم فيها تصنيف مستخدم على أنّه غير مؤهَّل ليصبح عميلاً محتملاً، بالإضافة إلى سبب عدم الأهلية.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة conversion_value الحدث، بتنسيق ISO 4217 المكوّن من 3 أحرف.

* في حال ضبط مَعلمة conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الأرباح بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث كحدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
disqualified_lead_reason string لا لا أريد الشراء يشير ذلك إلى سبب تصنيف عميل مهتم على أنّه غير مؤهَّل.

مثال

يوضّح المثال التالي كيفية إرسال حدث disqualify_lead باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "disqualify_lead",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "currency": "USD",
      "conversionValue": 30.03,
      "additionalEventParameters": [
        {
          "parameterName": "disqualified_lead_reason",
          "value": "Not looking to buy"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "disqualify_lead",
      "params": {
        "currency": "USD",
        "value": 30.03,
        "disqualified_lead_reason": "Not looking to buy"
      }
    }]
  })
});

generate_lead

يقيس هذا الحدث الحالات التي تم فيها اكتساب عميل محتمل (على سبيل المثال، من خلال نموذج). سجِّل هذا الحدث لفهم مدى فعالية حملاتك التسويقية وعدد العملاء الذين يعاودون التفاعل مع نشاطك التجاري بعد تجديد النشاط التسويقي لهم.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة conversion_value الحدث، بتنسيق ISO 4217 المكوّن من 3 أحرف.

* في حال ضبط مَعلمة conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الأرباح بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث كحدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
lead_source string لا معرض تجاري مصدر العميل المحتمل

مثال

يوضّح المثال التالي كيفية إرسال حدث generate_lead باستخدام واجهة برمجة التطبيقات لإدارة بيانات "إعلانات Google". في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "generate_lead",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "currency": "USD",
      "conversionValue": 30.03,
      "additionalEventParameters": [
        {
          "parameterName": "lead_source",
          "value": "Trade show"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "generate_lead",
      "params": {
        "currency": "USD",
        "value": 30.03,
        "lead_source": "Trade show"
      }
    }]
  })
});

qualify_lead

يقيس هذا الحدث الحالات التي يتم فيها وضع علامة على مستخدم تفيد بأنّه يستوفي معايير التأهّل ليصبح عميلاً محتملاً مؤهّلاً.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة conversion_value الحدث، بتنسيق ISO 4217 المكوّن من 3 أحرف.

* في حال ضبط مَعلمة conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الأرباح بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث كحدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط السمة currency في حال ضبط السمة conversion_value.

مثال

يوضّح المثال التالي كيفية إرسال حدث qualify_lead باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "qualify_lead",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "currency": "USD",
      "conversionValue": 30.03
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "qualify_lead",
      "params": {
        "currency": "USD",
        "value": 30.03
      }
    }]
  })
});

working_lead

يقيس هذا الحدث الحالات التي يتواصل فيها المستخدم مع أحد الممثلين أو يتواصل ممثل معه.

حقول الحدث

الاسم النوع مطلوب مثال على القيمة الوصف
currency string نعم* دولار أمريكي عملة conversion_value الحدث، بتنسيق ISO 4217 المكوّن من 3 أحرف.

* في حال ضبط مَعلمة conversion_value، تكون مَعلمة currency مطلوبة لاحتساب مقاييس الأرباح بدقة.
conversion_value number نعم* 30.03 يشير ذلك إلى القيمة النقدية للحدث.

* تكون مَعلمة conversion_value مطلوبة عادةً لإعداد تقارير ذات مغزى. إذا صنّفت الحدث كحدث رئيسي، ننصحك بضبط المَعلمة conversion_value.
* يجب ضبط مَعلمة currency في حال ضبط مَعلمة conversion_value.

المعلمات

الاسم النوع مطلوب مثال على القيمة الوصف
lead_status string لا المحادثات التي تم بدؤها حالة العميل المحتمل

مثال

يوضّح المثال التالي كيفية إرسال حدث working_lead باستخدام واجهة برمجة التطبيقات لإدارة بيانات إعلانات Google. في حال الترقية من Measurement Protocol، استخدِم علامات التبويب لنقل طلباتك إلى Data Manager API.

Data Manager API


{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "loginAccount": {
        "accountType": "GOOGLE_ANALYTICS_PROPERTY",
        "accountId": "GOOGLE_ANALYTICS_PROPERTY_ID"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ],
  "events": [
    {
      "eventName": "working_lead",
      "eventTimestamp": "2025-06-10T23:42:33-05:00",
      "eventSource": "WEB",
      "clientId": "CLIENT_ID",
      "currency": "USD",
      "conversionValue": 30.03,
      "additionalEventParameters": [
        {
          "parameterName": "lead_status",
          "value": "Started conversations"
        }
      ]
    }
  ]
}

Measurement Protocol

const measurementId = 'G-XXXXXXXXXX';
const apiSecret = '<secret_value>';
 
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    "client_id": "client_id",
    "events": [{
      "name": "working_lead",
      "params": {
        "currency": "USD",
        "value": 30.03,
        "lead_status": "Started conversations"
      }
    }]
  })
});