إرسال أحداث 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 وخاصيّة المستخدِم 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 الحدث أو خاصية المستخدم.

القيود

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

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

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