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

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

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

• بالنسبة إلى مصادر بيانات المواقع الإلكترونية (التي يتم عادةً قياسها باستخدام gtag.js أو "إدارة العلامات من Google")، يمكنك استخدام 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

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

Firebase gtag.js

تعرض هذه العلامة تبويب تعليمات لإرسال الأحداث من خادمك التي تتوافق مع نشاط المستخدم في تدفق تطبيق باستخدام حزمة تطوير البرامج (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. انسخ القيمة السرية.

   ملاحظة مهمة: يكون api_secret خاصًا. لا تعرضه في الرمز البرمجي من جهة العميل لموقعك الإلكتروني أو تطبيقك.

   • مخاطر أمنية: يؤدي الكشف عن api_secret إلى السماح لجهات غير مصرّح لها بإرسال بيانات عشوائية أو غير مرغوب فيها إلى موقعك على "إحصاءات Google"، ما قد يؤدي إلى إتلاف تقاريرك.
   • الاستخدام الصحيح: تم تصميم Measurement Protocol في الأساس للاستخدام في بيئات من جهة الخادم أو البيئات الموثوقة (مثل الأنظمة غير المتصلة بالإنترنت أو الاتصال بين الخادم والخادم).
   • التتبُّع من جهة العميل: إذا كنت بحاجة إلى إرسال الأحداث مباشرةً من متصفّح ويب، استخدِم علامة تتبُّع من Google‏ (gtag.js) أو Google Tag Manager.
   • إضافات Chrome: بالنسبة إلى إضافات Chrome المتوافقة مع الإصدار 3 من Manifest، لا يمكنك تحميل الرمز البرمجي عن بُعد، مثل gtag.js. في هذه الحالة، ننصحك باستخدام Measurement Protocol. اطّلِع على استخدام "إحصاءات Google" في إضافات Chrome.

رقم تعريف تطبيق 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

ملاحظة: إذا أردت جمع بياناتك في الاتحاد الأوروبي، غيِّر HOST في المثال إلى region1.google-analytics.com.

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

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

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

  {
   "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، راجِع المستندات المرجعية الخاصة بمعرّف مثيل التطبيق.

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

تجربة الميزة

ملاحظة: تستخدم الأمثلة التالية واجهة برمجة التطبيقات fetch وهي مخصّصة للاستخدام في بيئات موثوقة أو من جهة الخادم (مثل Node.js أو خادم الخلفية). ويجب عدم استخدامها في الرمز البرمجي من جهة العميل (المتصفح) لأنّ ذلك سيؤدي إلى الكشف عن api_secret.

في ما يلي مثال يمكنك استخدامه لإرسال أحداث متعددة في وقت واحد. يرسل هذا المثال الحدث 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":

ملاحظة: للحصول على معلومات حول قيود ميزات "إحصاءات Google‏ 360"، اطّلِع على مقالة إحصاءات Google‏ 360.

• يمكن أن تتضمّن الطلبات 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" في "إعلانات Google" لمستخدمي التطبيق.

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

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

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

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

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

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