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

يوفر FCM ثلاث مجموعات من الأدوات لمساعدتك في الحصول على نظرة ثاقبة لتسليم الرسائل:

• تقارير تسليم رسائل وحدة تحكم Firebase
• مقاييس تسليم Android SDK المجمعة من Firebase Cloud Messaging Data API
• تصدير البيانات الشامل إلى Google BigQuery

تتطلب جميع أدوات إعداد التقارير الموضحة في هذه الصفحة Google Analytics حتى تعمل. إذا لم يتم تمكين Google Analytics لمشروعك ، فيمكنك إعداده في علامة تبويب الدمج لإعدادات مشروع Firebase.

ضع في اعتبارك أن الإبلاغ عن العديد من الإحصائيات على هذه الصفحة ، يخضع لتأخيرات تصل إلى 24 ساعة بسبب تجميع بيانات التحليلات.

تقارير تسليم الرسائل

في علامة التبويب "التقارير" في وحدة تحكم Firebase ، يمكنك عرض البيانات التالية للرسائل المرسلة إلى تطبيقات FCM SDK لمنصة Android أو Apple ، بما في ذلك تلك المرسلة عبر مؤلف الإشعارات وواجهات برمجة تطبيقات FCM:

• يرسل - تم وضع رسالة البيانات أو رسالة الإعلام في قائمة الانتظار للتسليم أو تم تمريرها بنجاح إلى خدمة جهة خارجية مثل APNs للتسليم. انظر عمر الرسالة لمزيد من المعلومات.
• تم الاستلام (متوفر فقط على أجهزة Android) - استلم التطبيق رسالة البيانات أو رسالة الإشعار. تتوفر هذه البيانات عندما يتم تثبيت FCM SDK 18.0.1 أو أعلى على جهاز Android المستلم.
• مرات الظهور (متاح فقط لرسائل الإشعارات على أجهزة Android) - تم عرض إشعار العرض على الجهاز أثناء وجود التطبيق في الخلفية.
• يفتح - فتح المستخدم رسالة الإعلام. يتم الإبلاغ فقط عن الإشعارات المستلمة عندما يكون التطبيق في الخلفية.

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

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

• النظام الأساسي (iOS أو Android)
• برنامج
• تسميات التحليلات المخصصة

إضافة تسميات التحليلات إلى الرسائل

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

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

• -
• ~
• %

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

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

بيانات التسليم المجمعة عبر FCM Data API

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

يوفر API جميع البيانات المتاحة لتطبيق معين. انظر الوثائق المرجعية API .

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

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

 {
  "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٪.

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

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

نسب مخرجات الرسالة

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

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

نسب أداء التسليم

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

الرسالة Insight Percentagess

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

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

يوفر تصدير BigQuery سجلات رسائل فردية حول قبول الرسالة من خلال الواجهة الخلفية لـ FCM وتسليم الرسائل في SDK على الجهاز (الخطوتان 2 و 4 من بنية FCM ). هذه البيانات مفيدة لضمان قبول الرسائل الفردية وتسليمها. اقرأ المزيد حول تصدير بيانات BigQuery في القسم التالي.

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

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

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

حدود API

الجداول الزمنية للبيانات المجمعة

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

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

تهدف المقاييس التي توفرها Firebase Cloud Messaging Data API إلى توفير نظرة ثاقبة للاتجاهات العامة لتسليم الرسائل. ومع ذلك ، فهي لا توفر تغطية بنسبة 100٪ لجميع سيناريوهات الرسائل. السيناريوهات التالية هي نتائج معروفة لا تنعكس في المقاييس.

الرسائل المطوية

لا تظهر الرسائل المطوية بواسطة رسالة أخرى في مجموعة البيانات.

رسائل للأجهزة غير النشطة

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

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

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

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

تقوم FCM بتقريب واستبعاد الأعداد التي لا تكون فيها الأحجام كبيرة بما يكفي.

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

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

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

• Android 20.1.0 أو أعلى.
• iOS 8.6.0 أو أعلى
• Firebase Web SDK 9.0.0 أو أعلى

انظر أدناه للحصول على تفاصيل حول تمكين تصدير البيانات لنظامي التشغيل Android و iOS .

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

1. اختيار واحد من الخيارات التالية:

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

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

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

2. اتبع التعليمات التي تظهر على الشاشة لتمكين BigQuery.

راجع ربط Firebase بـ BigQuery للحصول على مزيد من المعلومات.

عند تمكين BigQuery Export لـ Cloud Messaging:

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

  • يمكنك جدولة عمليات إعادة تعبئة البيانات يدويًا لمدة تصل إلى الثلاثين يومًا الماضية.

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

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

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

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

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

يمكن لأجهزة iOS المزودة بـ FCM SDK 8.6.0 أو أعلى تمكين تصدير بيانات تسليم رسائل التطبيق. يدعم FCM تصدير البيانات لكل من إشعارات التنبيه والخلفية. قبل تمكين هذه الخيارات ، يجب عليك أولاً إنشاء رابط FCM-BiqQuery لمشروعك كما هو موضح في 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 API ، فتأكد من تحديد 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;