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

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

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

  • بالنسبة إلى مصادر البيانات من المواقع الإلكترونية (التي يتم قياسها عادةً باستخدام gtag.js أو Google Tag Manager)، يمكنك استخدام measurement_id في عنوان URL للطلب وclient_id في نص JSON لتحديد مثيل المستخدم. يجب أن يتطابق client_id مع رقم التعريف الذي أنشأته علامة "إحصاءات Google" على موقعك الإلكتروني.
  • بالنسبة إلى مصادر بيانات التطبيقات (التي تم قياسها باستخدام Firebase SDK)، يمكنك استخدام 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 لبروتوكول القياس. وفي ما يلي مثال لذلك:

  {
   "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 وكيفية استرداده باستخدام Firebase SDK، يُرجى الاطّلاع على المستندات المرجعية حول 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 مَعلمات مخصّصة كحدّ أقصى.

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

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

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

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

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

أسماء الأحداث التالية هي نقاط شائعة للالتباس:

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