إرسال أحداث Measurement Protocol إلى "إحصاءات Google"

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

اختَر المنصة التي تريد الاطّلاع عليها في هذا الدليل:

تهيئة الطلب

لا يتيح برنامج Measurement Protocol في "إحصاءات Google" سوى طلبات HTTP POST.

لإرسال حدث، استخدِم التنسيق التالي:

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

يجب توفير ما يلي في عنوان URL للطلب:

• api_secret: واجهة برمجة التطبيقات السرّية التي تم إنشاؤها في واجهة مستخدم "إحصاءات Google".

  لإنشاء مفتاح سرّي جديد، انتقِل إلى المشرف > جمع البيانات وتعديلها > مصادر البيانات > اختَر مصدر بياناتك > المفاتيح السرية لواجهة برمجة التطبيقات Measurement Protocol > إنشاء.

• استبدِل measurement_id برقم تعريف القياس المرتبط بمصدر بيانات، والذي يمكن العثور عليه في واجهة مستخدم "إحصاءات Google" ضمن المشرف > مصادر البيانات > اختَر مصدر بياناتك > رقم تعريف القياس.

  measurement_id ليس رقم تعريف مصدر البيانات.

يجب تقديم نص الطلب بتنسيق نص POST بتنسيق JSON لبروتوكول القياس. وفي ما يلي مثال لذلك:

  {
   "client_id": "CLIENT_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

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

التجربة الآن

في ما يلي مثال يمكنك استخدامه لإرسال أحداث متعددة في وقت واحد. يرسل هذا المثال الحدث tutorial_begin والحدث join_group إلى خادم "إحصاءات Google"، ويتضمّن معلومات جغرافية باستخدام الحقل user_location، ويتضمّن معلومات الجهاز باستخدام الحقل device.

const measurementId = "MEASUREMENT_ID";
const apiSecret = "API_SECRET";

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",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    device: {
      category: "mobile",
      language: "en",
      screen_resolution: "1280x2856",
      operating_system: "Android",
      operating_system_version: "14",
      model: "Pixel 9 Pro",
      brand: "Google",
      browser: "Chrome",
      browser_version: "136.0.7103.60"
    }
  })
});

الطابع الزمني للإلغاء

يستخدِم Measurement Protocol الطابع الزمني الأول الذي يعثر عليه في القائمة التالية لكل حدث في الطلب:

1. تمثّل هذه السمة timestamp_micros الفعالية.
2. timestamp_micros الطلب
3. الوقت الذي تتلقّى فيه منصّة Measurement Protocol الطلب

يرسل المثال التالي طابعًا زمنيًا على مستوى الطلب ينطبق على جميع الأحداث في الطلب. نتيجةً لذلك، يحدّد Measurement Protocol الطابع الزمني requestUnixEpochTimeInMicros لكلّ من الحدثَين tutorial_begin وjoin_group.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ]
}

يرسل المثال التالي طابعًا زمنيًا على مستوى الطلب وطابعًا زمنيًا على مستوى الحدث. نتيجةً لذلك، يحدّد Measurement Protocol الطابع الزمني tutorialBeginUnixEpochTimeInMicros للحدث tutorial_begin، والطابع الزمني requestUnixEpochTimeInMicros للحدث join_group.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ]
}

القيود

تنطبق القيود التالية على إرسال أحداث Measurement Protocol إلى "إحصاءات Google":

• يمكن أن تتضمّن الطلبات 25 حدثًا كحدّ أقصى.
• يمكن أن تحتوي الأحداث على 25 معلَمة كحدّ أقصى.
• يمكن أن تحتوي الأحداث على 25 خاصيّة مستخدم كحدّ أقصى.
• يجب أن تحتوي أسماء خصائص المستخدمين على 24 حرفًا أو أقل.
• يجب أن تحتوي قيم خصائص المستخدمين على 36 حرفًا أو أقل.
• يجب أن تحتوي أسماء الأحداث على 40 حرفًا أو أقل، وأن تحتوي على أحرف أبجدية رقمية وشرطات سفلية فقط، ويجب أن تبدأ بحرف أبجدي.
• يجب أن تحتوي أسماء المَعلمات، بما في ذلك مَعلمات السلع، على 40 حرفًا أو أقل، وأن تحتوي على أحرف أبجدية رقمية وشرطات سفلية فقط، ويجب أن تبدأ بحرف أبجدي.
• يجب أن تحتوي قيم المَعلمات، بما في ذلك قيم مَعلمات السلع، على 100 حرف أو أقلّ في موقع عادي على "إحصاءات Google"، و500 حرف أو أقلّ في موقع على "إحصاءات Google‏ 360".
• يمكن أن تحتوي مَعلمات المنتجات أو الخدمات على 10 مَعلمات مخصّصة كحدّ أقصى.
• يجب أن يكون حجم نص المشاركة أقل من 130 كيلوبايت.
• لا تملأ أحداث App Measurement Protocol المُرسَلة إلى "إحصاءات Google" شرائح جمهور "بحث Google" في "إعلانات Google" لمستخدمي التطبيق.

للاطّلاع على المتطلبات الإضافية لكل حالة استخدام، يُرجى الرجوع إلى حالات الاستخدام الشائعة.