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

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

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

Firebase gtag.js

تهيئة الطلب

لا تتيح منصة 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: مفتاح API السري الذي تم إنشاؤه في واجهة مستخدم "إحصاءات Google".

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

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

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

اطّلِع على مَعلمات طلب البحث للحصول على المرجع الكامل.

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

• client_id: معرّف فريد لعميل. يختلف ذلك عن app_instance_id Firebase. استخدِم gtag.js('get').

• ‫user_id: اختياري. هي معرّف فريد لعميل. يجب أن تتضمّن أحرف UTF-8 فقط. اطّلِع على رقم تعريف User-ID للتحليل من عدّة منصات للحصول على مزيد من المعلومات عن هذا المعرّف.

• ‫consent: اختياري. تعرَّف على كيفية ضبط إعدادات الموافقة.

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

• ‫events: مصفوفة من عناصر الأحداث يمكنك تضمين عدة أحداث في طلب واحد.

  لكي يظهر نشاط المستخدِم في تقارير مثل الوقت الفعلي، يجب تقديم engagement_time_msec وsession_id كجزء من params لevent. يجب أن تشير المَعلمة engagement_time_msec إلى مدة التفاعل مع الحدث بالملّي ثانية.

  وفي ما يلي مثال لذلك:

  {
   "client_id": "123456.7654321",
   "events": [
     {
        "name": "campaign_details",
        "params": {
          "campaign_id": "google_1234",
          "campaign": "Summer_fun",
          "source": "google",
          "medium": "cpc",
          "term": "summer+travel",
          "content": "logolink",
          "session_id": "123",
          "engagement_time_msec": 100
        }
     }
   ]
  }

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

تجربة الميزة

في ما يلي مثال يمكنك استخدامه لإرسال أحداث متعددة في آنٍ واحد. يُرسِل هذا المثال حدث tutorial_begin وحدث join_group إلى خادم "إحصاءات Google".

const measurement_id = `G-XXXXXXXXXX`;
const api_secret = `<secret_value>`;

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: "XXXXXXXXXX.YYYYYYYYYY",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "123",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "123",
          "engagement_time_msec": 150
        }
      }
    ]
  })
});

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

يستخدِم 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":

ملاحظة: للحصول على معلومات عن القيود المفروضة على ميزات "إحصاءات Google‏ 360"، يُرجى الاطّلاع على إحصاءات Google 360.

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

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