فهم تسليم الرسائل

عند عرض تقارير الرسائل، يمكنك ضبط نطاق زمني للبيانات المعروضة، مع خيار التصدير إلى ملف CSV. يمكنك أيضًا الفلترة حسب المعايير التالية:

• النظام الأساسي (iOS أو Android)
• التطبيق
• تصنيفات الإحصاءات المخصّصة

إضافة تصنيفات الإحصاءات إلى الرسائل

إنّ تصنيف الرسائل مفيد جدًا للتحليل المخصّص، ما يتيح لك فلترة إحصاءات التسليم حسب التصنيفات أو مجموعات التصنيفات. يمكنك إضافة تصنيف إلى أي رسالة يتم إرسالها من خلال واجهة برمجة التطبيقات HTTP v1 API من خلال ضبط حقل fcmOptions.analyticsLabel في عنصر message، أو في الحقلَين AndroidFcmOptions أو ApnsFcmOptions الخاصَّين بالنظام الأساسي.

تصنيفات "إحصاءات YouTube" هي سلاسل نصية بالتنسيق ^[a-zA-Z0-9-_.~%]{1,50}$. يمكن أن تتضمّن التصنيفات أحرفًا لاتينية صغيرة وكبيرة وأرقامًا والرموز التالية:

• -
• ~
• %

الحد الأقصى للطول هو 50 حرفًا. يمكنك تحديد ما يصل إلى 100 تصنيف فريد في اليوم، ولا يتم تسجيل الرسائل التي تحتوي على تصنيفات تمّت إضافتها بعد هذا الحدّ.

في علامة التبويب Firebase تقارير رسائل وحدة التحكّم، يمكنك البحث في قائمة بجميع التصنيفات الحالية وتطبيقها بشكل فردي أو ممزوج لتصفية الإحصاءات المعروضة.

بيانات الإرسال المجمّعة من خلال واجهة برمجة التطبيقات FCM Data API

تتيح لك واجهة برمجة التطبيقات Firebase Cloud Messaging Data API استرداد معلومات يمكنها مساعدتك في فهم نتائج طلبات الرسائل الموجّهة إلى تطبيقات Android. توفّر واجهة برمجة التطبيقات بيانات مجمّعة على مستوى جميع أجهزة Android المزوّدة بميزة جمع البيانات في المشروع. ويشمل ذلك تفاصيل عن النسبة المئوية للرسائل التي تم تسليمها بدون تأخير، بالإضافة إلى عدد الرسائل التي تم تأخيرها أو إسقاطها ضمن طبقة النقل في Android. يمكن أن يؤدي تقييم هذه البيانات إلى الكشف عن مؤشرات عامة في إرسال الرسائل ومساعدتك في العثور على طرق فعّالة لتحسين أداء طلبات الإرسال. اطّلِع على المخططات الزمنية المجمّعة للبيانات للحصول على معلومات عن مدى توفّر النطاق الزمني في التقارير.

توفّر واجهة برمجة التطبيقات جميع البيانات المتاحة لتطبيق معيّن. اطّلِع على المستندات المرجعية لواجهات برمجة التطبيقات.

كيف يتم تقسيم البيانات؟

يتم تقسيم بيانات التسليم حسب التطبيق والتاريخ وتصنيف الإحصاءات. سيؤدي طلب البيانات من واجهة برمجة التطبيقات إلى عرض البيانات لكل مجموعة من التاريخ والتطبيق وتصنيف الإحصاءات. على سبيل المثال، سيظهر كائن JSON واحد من النوع androidDeliveryData على النحو التالي:

 {
  "appId": "1:23456789:android:a93a5mb1234efe56",
  "date": {
    "year": 2021,
    "month": 1,
    "day": 1
  },
  "analyticsLabel": "foo",
  "data": {
    "countMessagesAccepted": "314159",
    "messageOutcomePercents": {
      "delivered": 71,
      "pending": 15
    },
   "deliveryPerformancePercents": {
      "deliveredNoDelay": 45,
      "delayedDeviceOffline": 11
    }
  }

كيفية تفسير المقاييس

توضِّح بيانات التسليم النسبة المئوية للرسائل التي تتطابق مع كلٍّ من المقاييس التالية. من الممكن أن تتطابق رسالة واحدة مع مقاييس متعددة. بسبب القيود المفروضة على كيفية جمع البيانات و مستوى الدقّة الذي جمعنا به المقاييس، لا يتمّ تمثيل بعض نتائج الرسائل في المقاييس على الإطلاق، لذلك لن تبلغ النسب المئوية أدناه %100.

عدد الرسائل المقبولة

العدد الوحيد المُدرَج في مجموعة البيانات هو عدد الرسائل التي تقبلها ميزة "المراسلة عبر السحابة الإلكترونية من Firebase" لتسليمها إلى أجهزة Android. تستخدِم جميع النِسب المئوية هذه القيمة كالكسر. يُرجى العِلم أنّ هذا العدد لن يشمل الرسائل المستهدفة بالمستخدمين الذين أوقفوا جمع معلومات الاستخدام والتشخيص على أجهزتهم.

النسب المئوية لمحصلات الرسائل

تقدّم الحقول المضمّنة في كائن MessageOutcomePercents معلومات عن نتائج طلبات الرسائل. تكون الفئات جميعها متعارضة مع بعضها. ويمكنه الإجابة عن أسئلة، مثل "هل يتم تسليم رسائلي؟" و "ما هو سبب إسقاط الرسائل؟"

على سبيل المثال، قد تشير القيمة العالية للحقل droppedTooManyPendingMessages إلى أنّ نُسخ التطبيق تتلقّى أعدادًا كبيرة من الرسائل غير القابلة للطي تتجاوز الحدّ الأقصى المسموح به في الحقل FCM، وهو 100 رسالة في انتظار المراجعة. للحدّ من هذه المشكلة، تأكَّد من أنّ تطبيقك يعالج المكالمات المرسَلة إلى onDeletedMessages، ويمكنك إرسال رسائل قابلة للطي. وبالمثل، قد تشير النسب المئوية العالية لحالة droppedDeviceInactive إلى ضرورة تعديل الرموز المميّزة للتسجيل على الخادم، وإزالة الرموز المميّزة القديمة وإلغاء اشتراكها في المواضيع. اطّلِع على مقالة إدارة الرموز المميّزة لتسجيل FCM للاطّلاع على أفضل الممارسات في هذا المجال.

النسب المئوية لأداء التسليم

تقدّم الحقول في عنصر DeliveryPerformancePercents معلومات عن الرسائل التي تم تسليمها بنجاح. ويمكنه الإجابة عن أسئلة مثل "هل تأخّرت رسائلي؟" و "لماذا تأخّرت الرسائل؟" على سبيل المثال، تشير القيمة العالية لسمة delayedMessageThrottled بوضوح إلى أنّك تتجاوز الحدود القصوى لكل جهاز، ويجب تعديل معدّل إرسال الرسائل.

النسب المئوية لإحصاءات الرسائل

يوفّر هذا العنصر معلومات إضافية عن جميع عمليات إرسال الرسائل. يعبّر الحقل priorityLowered عن النسبة المئوية للرسائل المقبولة التي تم خفض أولويتها من HIGH إلى NORMAL. إذا كانت هذه القيمة مرتفعة، حاوِل إرسال عدد أقل من الرسائل ذات الأولوية العالية أو تأكَّد من عرض إشعار دائمًا عند إرسال رسالة ذات أولوية عالية. اطّلِع على مستنداتنا حول أولوية الرسائل للحصول على مزيد من المعلومات.

كيف تختلف هذه البيانات عن البيانات التي يتم تصديرها إلى BigQuery؟

يوفّر تصدير BigQuery سجلّات رسائل فردية حول قبول الرسائل من قِبل الخلفية في "المراسلة عبر السحابة الإلكترونية من Firebase" وتسليم الرسائل في حزمة تطوير البرامج (SDK) على الجهاز (الخطوتان 2 و4 من بنية "المراسلة عبر السحابة الإلكترونية من Firebase"). هذه البيانات مفيدة للتأكّد من قبول الرسائل الفردية ونقلها. يمكنك الاطّلاع على مزيد من المعلومات عن تصدير بيانات BigQuery في القسم التالي.

في المقابل، توفّر واجهة برمجة التطبيقات Firebase Cloud Messaging Data API تفاصيل مجمّعة حول ما يحدث تحديدًا في طبقة النقل في Android (أو الخطوة 3 من بنية FCM). تقدّم هذه البيانات إحصاءات عن تسليم الرسائل من الخلفيات في إطار عمل Firebase إلى حزمة تطوير البرامج (SDK) لنظام التشغيل Android. وهو مفيد بشكل خاص لمحاولة معرفة سبب تأخّر الرسائل أو إسقاطها أثناء عملية النقل هذه.

في بعض الحالات، من الممكن ألا تتطابق مجموعتا البيانات بدقة بسبب ما يلي:

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

قيود واجهة برمجة التطبيقات

المخططات الزمنية للبيانات المجمّعة

ستعرِض واجهة برمجة التطبيقات البيانات السابقة لـ 7 أيام، ولكن سيتم تأخير البيانات التي تعرِضها هذه الواجهة لمدة تصل إلى 5 أيام. على سبيل المثال، في 20 كانون الثاني (يناير)، ستكون البيانات متاحة من 9 كانون الثاني (يناير) إلى 15 كانون الثاني (يناير)، ولكن ليس ليوم 16 كانون الثاني (يناير) أو اللاحق. بالإضافة إلى ذلك، يتم تقديم البيانات بأفضل ما يمكن. في حال تعطُّل البيانات، سيعمل نظام FCM على حلّ المشاكل في المستقبل ولن يُعيد تعبئة البيانات بعد حلّ المشكلة. في حالات انقطاع الخدمة على نطاق أوسع، قد لا تتوفّر البيانات لمدة أسبوع أو أكثر.

تغطية البيانات

تهدف المقاييس التي تقدّمها Firebase Cloud Messaging Data API إلى تقديم إحصاءات عن المؤشرات العامة لتسليم الرسائل. ومع ذلك، لا توفّر هذه السيناريوهات تغطية بنسبة% 100 لجميع سيناريوهات الرسائل. السيناريوهات التالية هي نتائج معروفة لا تظهر في المقاييس.

الرسائل المنتهية الصلاحية

إذا انتهت صلاحية مدة البقاء (TTL) بعد نهاية تاريخ السجلّ المحدّد، لن يتم احتساب الرسالة على أنّها droppedTtlExpired في هذا التاريخ.

الرسائل المرسَلة إلى الأجهزة غير النشطة

قد تظهر الرسائل المُرسَلة إلى الأجهزة غير النشطة في مجموعة البيانات أو لا تظهر، وذلك استنادًا إلى مسار البيانات الذي تسلكه. ويمكن أن يؤدي ذلك إلى بعض الأخطاء في احتساب الحقلَين droppedDeviceInactive وpending.

الرسائل المُرسَلة إلى الأجهزة التي تتضمّن إعدادات مفضّلة معيّنة للمستخدم

بالنسبة إلى المستخدمين الذين أوقفوا جمع معلومات الاستخدام والبيانات التشخيصية على أجهزتهم، لن يتم تضمين رسائلهم في عملية الاحتساب، وذلك بما يتوافق مع إعداداتهم المفضّلة.

التقريب والحدّ الأدنى

تعمل خدمة "إدارة عناوين البريد الإلكتروني للعملاء" على تقريب الأعداد واستبعادها عمدًا عندما لا تكون الأعداد كبيرة بالقدر الكافي.

تصدير بيانات BigQuery

يمكنك تصدير بيانات الرسائل إلى BigQuery لإجراء مزيد من التحليلات. تتيح لك أداة BigQuery تحليل البيانات باستخدام لغة الاستعلامات البنيوية (SQL) في BigQuery، أو تصديرها إلى مقدّم خدمات سحابة تقنية أخرى، أو استخدام البيانات في نماذج تعلُّم الآلة المخصّصة. يتضمّن التصدير إلى BigQuery جميع البيانات المتاحة للرسائل، بغض النظر عن نوع الرسالة أو ما إذا تم إرسال الرسالة من خلال واجهة برمجة التطبيقات أو أداة إنشاء الإشعارات.

بالنسبة إلى الرسائل المُرسَلة إلى الأجهزة التي تعمل بالإصدارات التالية من حزمة FCM SDK، يمكنك تفعيل خيار تصدير بيانات إرسال الرسائل لتطبيقك:

• الإصدار 20.1.0 من نظام التشغيل Android أو إصدار أحدث
• الإصدار 8.6.0 من نظام التشغيل iOS أو إصدار أحدث
• الإصدار 9.0.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) على الويب من Firebase

يُرجى الاطّلاع أدناه على تفاصيل حول تفعيل ميزة تصدير البيانات على Android و iOS.

للبدء، اربط مشروعك بخدمة BigQuery:

1. اختَر أحد الخيارات التالية:

   • افتح أداة إنشاء الإشعارات، ثم انقر على الوصول إلى BigQuery في أسفل الصفحة.

   • من صفحة عمليات الدمج في وحدة تحكّم Firebase، انقر على ربط في بطاقة BigQuery.

     تعرض هذه الصفحة خيارات تصدير FCM لجميع التطبيقات المفعّلة التي تستخدم FCM في المشروع.

2. اتّبِع التعليمات الظاهرة على الشاشة لتفعيل BigQuery.

يُرجى الاطّلاع على مقالة ربط Firebase بخدمة BigQuery لمزيد من المعلومات.

عند تفعيل تصدير BigQuery إلى Cloud Messaging:

• تُصدِّر Firebase بياناتك إلى BigQuery. يُرجى ملاحظة أنّ عملية النشر الأولي للبيانات المخصّصة للتصدير قد تستغرق ما يصل إلى 48 ساعة.

  • يمكنك تحديد جدول زمني يدويًا لإضافة البيانات السابقة لمدة تصل إلى آخر 30 يومًا.

• بعد إنشاء مجموعة البيانات، لا يمكن تغيير الموقع الجغرافي، ولكن يمكنك نسخ مجموعة البيانات إلى موقع جغرافي مختلف أو نقل مجموعة البيانات يدويًا (إعادة إنشائها) في موقع جغرافي مختلف. للاطّلاع على معلومات أكثر، يُرجى الاطّلاع على مقالة تغيير موقع مجموعة البيانات.

• تُعدّ Firebase عمليات مزامنة منتظمة لبياناتك من مشروعك على Firebase إلى BigQuery. تبدأ عمليات التصدير اليومية هذه في الساعة 4:00 صباحًا بتوقيت المحيط الهادئ، وينتهي عادةً تنفيذها في غضون 24 ساعة.

• يتم تلقائيًا ربط جميع التطبيقات في مشروعك بمنصّة BigQuery، وبالنسبة إلى أي تطبيقات تتم إضافتها إلى المشروع لاحقًا، يتم أيضًا ربطها تلقائيًا بمنصّة BigQuery. يمكنك إدارة اختيار التطبيقات التي ترسل البيانات.

لإيقاف تصدير BigQuery، ألغِ ربط مشروعك في وحدة تحكّم Firebase.

تفعيل تصدير بيانات تسليم الرسائل

يمكن لأجهزة iOS التي تعمل بإصدار FCM SDK 8.6.0 أو إصدار أحدث تفعيل ميزة تصدير بيانات إرسال الرسائل في تطبيقاتها. FCM تتيح تصدير البيانات لكل من الإشعارات التنبيهية والإشعارات التي تعمل في الخلفية. قبل تفعيل هذين الخيارَين، عليك أولاً إنشاء رابط FCM-BigQuery لمشروعك كما هو موضّح في مقالة تصدير بيانات BigQuery.

تفعيل تصدير بيانات التسليم لإشعارات التنبيهات

وبما أنّ إشعارات التنبيهات هي فقط التي يمكنها تنشيط إضافات تطبيق خدمة الإشعارات، عليك إضافة إضافة خدمة إشعارات إلى تطبيقك واستدعاء واجهة برمجة التطبيقات هذه داخل إضافة خدمة لتفعيل تتبُّع الرسائل المعروضة. اطّلِع على مستندات Apple حول تعديل المحتوى في الإشعارات التي تم تسليمها حديثًا.

يجب إجراء المكالمة التالية لكل إشعار يتم تلقّيه:

// For alert notifications, call the API inside the service extension:
class NotificationService: UNNotificationServiceExtension {
  override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
  Messaging.extensionHelper()
      .exportDeliveryMetricsToBigQuery(withMessageInfo:request.content.userInfo)
  }
}

// For alert notifications, call the API inside the service extension:
@implementation NotificationService
- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request
                   withContentHandler:(void (^)(UNNotificationContent *_Nonnull))contentHandler {
  [[FIRMessaging extensionHelper] exportDeliveryMetricsToBigQueryWithMessageInfo:request.content.userInfo];
}
@end

إذا كنت بصدد إنشاء طلبات إرسال باستخدام واجهة برمجة التطبيقات HTTP v1، احرص على تحديد mutable-content = 1 في عنصر الحمولة.

تفعيل تصدير بيانات الإرسال للإشعارات التي تعمل في الخلفية

بالنسبة إلى الرسائل التي يتم تلقّيها في الخلفية عندما يكون التطبيق في المقدّمة أو الخلفية، يمكنك طلب بيانات تصدير واجهة برمجة التطبيقات داخل معالِج رسائل البيانات في التطبيق الرئيسي. يجب إجراء هذا الطلب لكل إشعار يتم تلقّيه:

// For background notifications, call the API inside the UIApplicationDelegate or NSApplicationDelegate method:
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) {
  Messaging.extensionHelper().exportDeliveryMetricsToBigQuery(withMessageInfo:userInfo)
}

// For background notifications, call the API inside the UIApplicationDelegate or NSApplicationDelegate method:
@implementation AppDelegate
- (void)application:(UIApplication *)application
    didReceiveRemoteNotification:(NSDictionary *)userInfo
          fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
  [[FIRMessaging extensionHelper] exportDeliveryMetricsToBigQueryWithMessageInfo:userInfo];
}
@end

ما هي البيانات التي يتم تصديرها إلى BigQuery؟

يُرجى العلم أنّ استهداف الرموز المميّزة القديمة أو عمليات التسجيل غير النشطة قد يؤدي إلى تضخيم بعض هذه الإحصاءات.

مخطّط الجدول الذي تم تصديره هو:

ما هي الإجراءات التي يمكنك اتّخاذها بشأن البيانات التي تم تصديرها؟

تقدّم الأقسام التالية أمثلة على طلبات البحث التي يمكنك تنفيذها في BigQuery باستخدام بيانات FCM التي تم تصديرها.

عدد الرسائل المُرسَلة حسب التطبيق

SELECT app_name, COUNT(1)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED'
  AND message_id != ''
GROUP BY 1;

احتساب عدد نُسخ التطبيق الفريدة التي تستهدفها الرسائل

SELECT COUNT(DISTINCT instance_id)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED';

احتساب عدد رسائل الإشعارات المُرسَلة

SELECT COUNT(1)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED'
  AND message_type = 'DISPLAY_NOTIFICATION';

احتساب عدد رسائل البيانات المُرسَلة

SELECT COUNT(1)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED'
  AND message_type = 'DATA_MESSAGE';

احتساب الرسائل المُرسَلة إلى موضوع أو حملة

SELECT COUNT(1)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED'
  AND bulk_id = your bulk id AND message_id != '';

لتتبُّع أحداث رسالة مُرسَلة إلى موضوع معيّن، عدِّل طلب البحث هذا بهدف استبدال AND message_id != '' بـ AND message_id = <your message id>;.

احتساب مدة التوسّع لموضوع أو حملة معيّنين

وقت بدء ميزة "النشر على نطاق واسع" هو وقت استلام الطلب الأصلي، ووقت الانتهاء هو وقت إنشاء آخر رسالة فردية تستهدف مثيلًا واحدًا.

SELECT
  TIMESTAMP_DIFF(
    end_timestamp, start_timestamp, MILLISECOND
  ) AS fanout_duration_ms,
  end_timestamp,
  start_timestamp
FROM (
    SELECT MAX(event_timestamp) AS end_timestamp
    FROM `project ID.firebase_messaging.data`
    WHERE
      _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
      AND event = 'MESSAGE_ACCEPTED'
      AND bulk_id = your bulk id
  ) sent
  CROSS JOIN (
    SELECT event_timestamp AS start_timestamp
    FROM `project ID.firebase_messaging.data`
    WHERE
      _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
      AND event = 'MESSAGE_ACCEPTED'
      AND bulk_id = your bulk id
      AND message_type = 'TOPIC'
  ) initial_message;

احتساب النسبة المئوية للرسائل التي تم تسليمها

SELECT
  messages_sent,
  messages_delivered,
  messages_delivered / messages_sent * 100 AS percent_delivered
FROM (
    SELECT COUNT(DISTINCT CONCAT(message_id, instance_id)) AS messages_sent
    FROM `project ID.firebase_messaging.data`
    WHERE
      _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
      AND event = 'MESSAGE_ACCEPTED'
  ) sent
  CROSS JOIN (
    SELECT COUNT(DISTINCT CONCAT(message_id, instance_id)) AS messages_delivered
    FROM `project ID.firebase_messaging.data`
    WHERE
      _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
      AND (event = 'MESSAGE_DELIVERED'
      AND message_id
      IN (
        SELECT message_id FROM `project ID.firebase_messaging.data`
        WHERE
          _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
          AND event = 'MESSAGE_ACCEPTED'
        GROUP BY 1
      )
  ) delivered;

تتبُّع جميع الأحداث لمعرّف رسالة ومعرّف مثيل معيّنين

SELECT *
FROM `project ID.firebase_messaging.data`
WHERE
    _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
    AND message_id = 'your message id'
    AND instance_id = 'your instance id'
ORDER BY event_timestamp;

احتساب وقت الاستجابة لمعرّف رسالة ومعرّف مثيل معيّنين

SELECT
  TIMESTAMP_DIFF(
    MAX(delivered_time), MIN(accepted_time), MILLISECOND
  ) AS latency_ms
FROM (
    SELECT event_timestamp AS accepted_time
    FROM `project ID.firebase_messaging.data`
    WHERE
      _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
      AND message_id = 'your message id'
      AND instance_id = 'your instance id'
      AND event = 'MESSAGE_ACCEPTED'
  ) sent
  CROSS JOIN (
    SELECT event_timestamp AS delivered_time
    FROM `project ID.firebase_messaging.data`
    WHERE
      _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD') AND
      message_id = 'your message id' AND instance_id = 'your instance id'
      AND (event = 'MESSAGE_DELIVERED'
  ) delivered;