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

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

تعتمد المعرّفات والمعلّمات المطلوبة لطلبات Measurement Protocol على ما إذا كنت تُرسِل الأحداث إلى مصدر بيانات من موقع إلكتروني أو مصدر بيانات من تطبيق.

  • بالنسبة إلى مصادر البيانات من المواقع الإلكترونية (التي يتم عادةً تتبُّعها باستخدام gtag.js أو "إدارة العلامات من Google")، يمكنك استخدام measurement_id في عنوان URL للطلب وclient_id في نص JSON لتحديد مثيل المستخدِم. يجب أن يتطابق client_id مع رقم التعريف الذي تنشئه علامة "إحصاءات Google" على موقعك الإلكتروني.
  • بالنسبة إلى مصادر البيانات من التطبيقات (التي يتم تتبُّعها باستخدام حزمة تطوير البرامج (SDK) لمنصة Firebase)، يمكنك استخدام firebase_app_id في عنوان URL للطلب وapp_instance_id في نص JSON، اللذين توفّرهما حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google لبرنامج Firebase".

يقدّم هذا الدليل أمثلة على كلا السيناريوهَين.

مكوّنات الطلب الرئيسية حسب نوع مصدر البيانات

المكوّن مصدر بيانات من موقع إلكتروني (gtag.js/إدارة العلامات من Google) مصدر بيانات من تطبيق (Firebase)
مَعلمة عنوان URL لمصدر البيانات measurement_id firebase_app_id
مَعلمة عنوان URL لواجهة برمجة التطبيقات السرّية مطلوب مطلوب
حقل نص JSON لرقم تعريف الجهاز client_id app_instance_id

اختَر النظام الأساسي الذي تريد عرضه في هذا الدليل:

تعرض علامة التبويب هذه تعليمات لإرسال الأحداث من الخادم التي تتوافق مع نشاط المستخدِم في مصدر بيانات من تطبيق باستخدام حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google لبرنامج Firebase". ضَع في اعتبارك أنّ هذه الطلبات تستخدِم firebase_app_id وapp_instance_id.

المتطلبات الأساسية

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

واجهة برمجة تطبيقات سرّية

يتم استخدام api_secret لمصادقة طلباتك. من المهم الحفاظ على سرية هذه الواجهة.

لإنشاء واجهة سرّية جديدة:

  1. انتقِل إلى إحصاءات Google وانتقِل إلى حسابك وموقعك.
  2. انقر على المشرف في أسفل يمين الصفحة.
  3. ضِمن جمع البيانات وتعديلها، انقر على مصادر البيانات.
  4. اختَر مصدر بيانات الويب أو التطبيق.
  5. انقر على واجهات برمجة التطبيقات السرّية في Measurement Protocol.
  6. انقر على إنشاء.
  7. أدخِل اسمًا مستعارًا للواجهة السرّية وانقر على إنشاء.

  8. انسخ قيمة الواجهة السرّية.

رقم تعريف تطبيق Firebase

يحدّد firebase_app_id تطبيقك على Firebase. وهو يختلف عن app_instance_id.

للعثور على رقم تعريف تطبيق Firebase:

  1. افتح مشروعك في وحدة تحكّم Firebase.
  2. انقر على رمز ترس الإعدادات بجانب نظرة عامّة على المشروع واختَر إعدادات المشروع.
  3. ضِمن علامة التبويب الإعدادات العامة ، انتقِل إلى قسم تطبيقاتك.
  4. اختَر تطبيق iOS أو Android معيّنًا.
  5. انسخ قيمة رقم تعريف التطبيق.

تهيئة الطلب

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

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

POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

يجب توفير ما يلي في مَعلمات طلب البحث في عنوان URL للطلب (راجِع المتطلبات الأساسية لمعرفة التفاصيل حول كيفية العثور على هذه القيم أو إنشائها):

  • api_secret: واجهة برمجة التطبيقات السرّية لمصادقة الطلب
  • firebase_app_id: رقم تعريف تطبيق Firebase لتطبيقك

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

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

يجب توفير app_instance_id في نص الطلب لتحديد عملية تثبيت فريدة لتطبيقك على الأجهزة الجوّالة. يُرجى العِلم أنّ هذا المعرّف يختلف عن firebase_app_id الذي يحدّد التطبيق نفسه. لمزيد من المعلومات عن الـ app_instance_id وكيفية استرداده باستخدام حزمة تطوير البرامج (SDK) لمنصة Firebase، راجِع الـ مستندات المرجعية لـ app_instance_id.

مع أنّ 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":

  • يمكنك إرسال ما لا يزيد عن 100 مليون طلب غير مرتبط بالإحالات الناجحة في الساعة لكل موقع. يكون الطلب غير مرتبط بالإحالات الناجحة إذا لم يكن أي من الأحداث في الـ طلب حدثًا رئيسيًا يتضمّن إحالة ناجحة في "إعلانات Google". إذا تجاوزت هذا الحدّ، يتجاهل Measurement Protocol جميع الطلبات غير المرتبطة بالإحالات الناجحة للموقع بدون إشعارك طوال الفترة المتبقية من الساعة.

  • يمكن أن تتضمّن الطلبات 25 حدثًا كحدّ أقصى.

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

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

  • يجب أن تحتوي أسماء خصائص المستخدمين على 24 حرفًا أو أقل.

  • يجب أن تحتوي قيم خصائص المستخدمين على 36 حرفًا أو أقل.

  • يجب أن تحتوي أسماء الأحداث على 40 حرفًا أو أقل، وأن تحتوي على أحرف أبجدية رقمية وشرطات سفلية فقط، ويجب أن تبدأ بحرف أبجدي.

  • يجب أن تحتوي أسماء المعلَمات بما في ذلك معلَمات السلع على 40 حرفًا أو أقل، وأن تحتوي على أحرف أبجدية رقمية وشرطات سفلية فقط، ويجب أن تبدأ بحرف أبجدي.

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

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

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

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

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

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

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

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

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

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