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

يوضّح هذا الدليل كيفية إرسال أحداث مصادر بيانات الويب والتطبيقات في Google Analytics Measurement Protocol إلى أحد خوادم "إحصاءات 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 > إنشاء.

• firebase_app_id: هو رقم تعريف تطبيق Firebase، ويمكن العثور عليه في وحدة تحكُّم Firebase ضمن إعدادات المشروع > عام > تطبيقاتك > رقم تعريف التطبيق.

  إنّ firebase_app_id ليس هو نفسه app_instance_id. يحدّد firebase_app_id تطبيقك، بينما يحدّد app_instance_id عملية تثبيت واحدة للتطبيق.

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

  {
   "app_instance_id": "APP_INSTANCE_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 firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_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"
    }
  })
});

إنّ تنسيق firebase_app_id خاص بالنظام الأساسي. راجِع رقم تعريف التطبيق ضمن ملفات إعداد Firebase وعناصره.

تجاوز الطابع الزمني

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

1. timestamp_micros للحدث أو خاصيّة المستخدِم
2. timestamp_micros للطلب
3. الوقت الذي يتلقّى فيه Measurement Protocol الطلب

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

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

يرسل المثال التالي طابعًا زمنيًا على مستوى الطلب وطابعًا زمنيًا على مستوى الحدث وطابعًا زمنيًا على مستوى خاصيّة المستخدِم. نتيجةً لذلك، يخصّص Measurement Protocol الطوابع الزمنية التالية:

• tutorialBeginUnixEpochTimeInMicros للحدث tutorial_begin
• customerTierUnixEpochTimeInMicros لخاصيّة المستخدِم customer_tier
• requestUnixEpochTimeInMicros للحدث join_group وخاصيّة المستخدِم newsletter_reader

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

سلوك التحقّق من الصحة للأحداث وخصائص المستخدِمين السابقة

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

• إذا لم يتم ضبط validation_behavior أو تم ضبطه على RELAXED، يقبل Measurement Protocol الحدث أو خاصيّة المستخدِم ولكنّه يتجاوز الطابع الزمني ويضبطه على 72 ساعة.
• إذا تم ضبط validation_behavior على ENFORCE_RECOMMENDATIONS، يرفض Measurement Protocol الحدث أو خاصيّة المستخدِم.

يجب أن تتلقّى "إحصاءات Google" الأحداث المرسَلة باستخدام Measurement Protocol والمخصّصة للانضمام إلى الأحداث التي يجمعها ‫SDK "إحصاءات Google لـ Firebase" أو gtag.js أو معالجتها معًا في غضون 48 ساعة من الطابع الزمني الأصلي للحدث من جهة العميل. قد لا تتم معالجة الأحداث التي يتم تلقّيها بعد هذا الوقت على النحو المتوقّع، لا سيما لأغراض مثل إسناد الإحالات الناجحة.

القيود

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

• يمكن أن تحتوي الطلبات على 25 حدثًا كحدّ أقصى.
• يمكن أن تحتوي الأحداث على 25 معلَمة كحدّ أقصى.
• يمكن أن تحتوي الأحداث على 25 خاصيّة مستخدم كحدّ أقصى.
• يجب أن تحتوي أسماء خصائص المستخدمين على 24 حرفًا أو أقل.
• يجب أن تحتوي قيم خصائص المستخدمين على 36 حرفًا أو أقل.
• يجب أن تحتوي أسماء الأحداث على 40 حرفًا أو أقل، وأن تحتوي على أحرف أبجدية رقمية وشرطات سفلية فقط، ويجب أن تبدأ بحرف أبجدي.
• يجب أن تحتوي أسماء المعلَمات بما في ذلك معلَمات السلع على 40 حرفًا أو أقل، وأن تحتوي على أحرف أبجدية رقمية وشرطات سفلية فقط، ويجب أن تبدأ بحرف أبجدي.

• يجب أن تحتوي قيم المعلَمات بما في ذلك قيم معلَمات السلع على 100 حرف أو أقل لموقع عادي على "إحصاءات Google"، و500 حرف أو أقل لموقع على "إحصاءات Google‏ 360".

  لا ينطبق هذا الحدّ على المَعلمتَين session_id وsession_number عندما يتم توفير قيمهما من خلال المتغيّرَين المضمّنَين المقابلَين، وهما رقم تعريف الجلسة في إحصاءات Google ورقم الجلسة في إحصاءات Google في "إدارة العلامات من Google".

• يمكن أن تحتوي معلَمات السلع على 10 معلَمات مخصّصة كحدّ أقصى.

• يجب أن يكون حجم نص المنشور أقل من 130 كيلوبايت.

• لا تملأ أحداث App Measurement Protocol التي يتم إرسالها إلى "إحصاءات Google" شرائح الجمهور المستندة إلى البحث في "إعلانات Google" لمستخدمي التطبيق.

• بعض أسماء الأحداث والمعلَمات وخصائص المستخدِمين محجوزة ولا يمكن استخدامها. راجِع الأسماء المحجوزة للحصول على التفاصيل.

الأسماء المحجوزة

يحتوي Measurement Protocol على عدة أسماء محجوزة لا يمكن استخدامها للأحداث أو المعلَمات أو خصائص المستخدِمين.

في ما يلي أسماء الأحداث التي تسبّب عادةً ارتباكًا:

• screen_view: لا يُسمح بهذا الحدث إلا لمصادر بيانات التطبيقات. بالنسبة إلى مصادر بيانات الويب، استخدِم page_view بدلاً من ذلك.
• ad_impression: لا يُسمح بهذا الحدث إلا لمصادر بيانات التطبيقات.
• in_app_purchase: لا يُسمح بهذا الحدث إلا لمصادر بيانات التطبيقات. بالنسبة إلى مصادر بيانات الويب، استخدِم الـ purchase بدلاً من ذلك.

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