Google is committed to advancing racial equity for Black communities. See how.
ترجمت واجهة Cloud Translation API‏ هذه الصفحة.
Switch to English

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

يوفر FCM أدوات لمساعدتك في الحصول على نظرة ثاقبة لتسليم الرسائل. بالإضافة إلى تقارير التسليم وتحليل مسار الإشعارات المدمج في وحدة تحكم Firebase ، توفر FCM تصديرًا شاملاً للبيانات إلى Google BigQuery.

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

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

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

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

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

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

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

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

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

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

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

  • -
  • ~
  • %

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

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

تحليل قمع الإخطار

يوضح لك تحليل مسار الإشعارات المدمج كيفية استجابة المستخدمين لإشعارات معينة يتم إرسالها من وحدة تحكم Firebase. يتضمن هذا العرض بيانات لأجهزة iOS و Android المستهدفة في الفئات التالية:

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

لمشاهدة تحليل مسار الإخطارات:

  1. في منشئ الإخطارات ، حدد علامة التبويب التنبيهات .
  2. انقر فوق رسالة مكتملة أو قيد التقدم في قائمة الرسائل. يتم عرض طريقة عرض موسعة بما في ذلك تحليل مسار التحويل.

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

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

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

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

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

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

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

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

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

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

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

بعد ربط مشروعك بـ BigQuery:

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

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

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

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

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

بالنسبة للرسائل المرسلة إلى أجهزة Android باستخدام FCM SDK 20.1.0 أو أعلى ، يمكنك تمكين تصدير بيانات تسليم الرسائل لتطبيقك. على الرغم من تعطيل تصدير هذه البيانات افتراضيًا على مستوى التطبيق ، يمكنك تمكينها على مستوى مثيل التطبيق ، مما يسمح لك بمنح المستخدمين النهائيين خيار تقديم الموافقة لك لتحليل بيانات تسليم الرسائل الخاصة بهم (موصى به). عند تعيين كلاهما ، يتجاوز الإعداد على مستوى المثيل الإعداد على مستوى التطبيق.

ضع في اعتبارك أنه قبل تمكين هذه الخيارات ، يجب عليك أولاً إنشاء رابط FCM-BiqQuery لمشروعك كما هو موضح في BigQuery تصدير البيانات .

تفعيل تصدير بيانات التسليم لمثيلات التطبيق

لتمكين تصدير البيانات تسليم الرسالة على أساس لكل التطبيق مثيل، استدعاء setDeliveryMetricsExportToBigQuery() طريقة لل FirebaseMessaging الطبقة وتمرير true . فمثلا:

ج 65f8ae990

استخدم هذه الطريقة مع الإعداد الافتراضي على مستوى التطبيق (معطل) لتزويد المستخدمين بخيار حجب أو تقديم الموافقة على تصدير البيانات.

لتعليق أو تعطيل التصدير ، قم باستدعاء الطريقة واجتاز false .

تفعيل تصدير بيانات التسليم لأحد التطبيقات

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

<application>
  <meta-data android:name="delivery_metrics_exported_to_big_query_enabled"
      android:value="true" />
</application>

لا يزال بإمكان التطبيقات التي تمكّن التصدير في البيان السماح للمستخدمين بإلغاء الاشتراك عن طريق تعيين قيمة false لـ setDeliveryMetricsExportToBigQuery() . يؤدي استدعاء هذه الطريقة في وقت التشغيل إلى تجاوز القيمة على مستوى التطبيق.

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

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

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

_PARTITIONTIME الطابع الزمني يحتوي هذا العمود الزائف على طابع زمني لبداية اليوم (بالتوقيت العالمي المنسق) الذي تم تحميل البيانات فيه. بالنسبة لقسم YYYYMMDD ، يحتوي هذا العمود الزائف على القيمة TIMESTAMP ('YYYY-MM-DD').
event_timestamp الطابع الزمني الطابع الزمني للحدث كما سجله الخادم
رقم المشروع عدد صحيح يحدد رقم المشروع المشروع الذي أرسل الرسالة
معرف الرسالة خيط يحدد معرف الرسالة الرسالة. تم إنشاؤه من معرف التطبيق والطابع الزمني ، قد لا يكون معرف الرسالة ، في بعض الحالات ، فريدًا بشكل عام.
example_id خيط معرف المثيل للتطبيق الذي تم إرسال الرسالة إليه (عند توفره)
نوع الرسالة خيط نوع الرسالة. يمكن أن تكون رسالة إعلام أو رسالة بيانات. يتم استخدام الموضوع لتحديد الرسالة الأصلية لموضوع أو حملة إرسال ؛ الرسائل اللاحقة إما إشعار أو رسالة بيانات.
sdk_platform خيط منصة التطبيق المستلم
اسم التطبيق خيط اسم الحزمة لتطبيقات Android أو معرف الحزمة لتطبيقات iOS
collapse_key خيط يحدد مفتاح الطي مجموعة من الرسائل التي يمكن تصغيرها. عندما لا يكون الجهاز متصلاً ، يتم وضع الرسالة الأخيرة فقط مع مفتاح الطي المحدد في قائمة الانتظار للتسليم النهائي
أفضلية عدد صحيح أولوية الرسالة. القيم الصالحة هي "عادية" و "عالية". في نظام iOS ، تتوافق هذه مع أولويات APNs 5 و 10
ttl عدد صحيح تحدد هذه المعلمة المدة (بالثواني) التي يجب أن تبقى فيها الرسالة في تخزين FCM إذا كان الجهاز غير متصل بالإنترنت
موضوع خيط اسم الموضوع الذي تم إرسال الرسالة إليه (عند الاقتضاء)
معرّف_الجملة عدد صحيح يحدد المعرف المجمع مجموعة من الرسائل ذات الصلة ، مثل إرسال معين إلى موضوع
حدث خيط نوع الحدث. القيم الممكنة هي:
  • MESSAGE_ACCEPTED: تم استلام الرسالة بواسطة خادم FCM والطلب صالح ؛
  • MESSAGE_DELIVERED: تم تسليم الرسالة إلى FCM SDK للتطبيق على الجهاز. بشكل افتراضي ، لا يتم نشر هذا الحقل. للتمكين ، اتبع التعليمات الواردة في [`setDeliveryMetricsExportToBigQuery (منطقي)`] (https://firebase.google.com/docs/reference/android/com/google/firebase/messaging/FirebaseMessaging#public-void-setdeliverymetricsexporttobigquery-boolean -ممكن)).
  • MISSING_REGISTRATIONS: تم رفض الطلب بسبب فقدان التسجيل ؛
  • UNAUTHORIZED_REGISTRATION: تم رفض الرسالة لأن المرسل غير مصرح له بإرسالها إلى التسجيل ؛
  • MESSAGE_RECEIVED_INTERNAL_ERROR: حدث خطأ غير محدد عند معالجة طلب الرسالة ؛
  • MISMATCH_SENDER_ID: تم رفض طلب إرسال رسالة بسبب عدم التطابق بين معرف المرسل الذي يرسل الرسالة ، والمعلن عن نقطة النهاية ؛
  • QUOTA_EXCEEDED: تم رفض طلب إرسال رسالة بسبب عدم كفاية الحصة ؛
  • INVALID_REGISTRATION: تم رفض طلب إرسال رسالة بسبب تسجيل غير صالح ؛
  • INVALID_PACKAGE_NAME: تم رفض طلب إرسال رسالة بسبب اسم حزمة غير صالح ؛
  • INVALID_APNS_CREDENTIAL: تم رفض طلب إرسال رسالة بسبب شهادة APNS غير صالحة ؛
  • INVALID_PARAMETERS: تم رفض طلب إرسال رسالة بسبب معلمات غير صالحة ؛
  • PAYLOAD_TOO_LARGE: تم رفض طلب إرسال رسالة بسبب حمولة أكبر من الحد ؛
  • AUTHENTICATION_ERROR: تم رفض طلب إرسال رسالة بسبب خطأ في المصادقة (تحقق من مفتاح API المستخدم لإرسال الرسالة) ؛
  • INVALID_TTL: تم رفض طلب إرسال رسالة لأن مدة البقاء (TTL) غير صالحة.
analytics_label خيط باستخدام HTTP v1 API ، يمكن تعيين تسمية التحليلات عند إرسال الرسالة ، من أجل تمييز الرسالة لأغراض التحليلات

ماذا يمكنك أن تفعل بالبيانات المصدرة؟

تقدم الأقسام التالية أمثلة على طلبات البحث التي يمكنك تشغيلها في 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;