درک تحویل پیام

FCM سه مجموعه از ابزارها را برای کمک به دریافت بینش در مورد تحویل پیام فراهم می کند:

• گزارش های تحویل پیام کنسول Firebase
• سنجه‌های تحویل Android SDK انبوه از Firebase Cloud Messaging Data API
• صادرات جامع داده به Google BigQuery

ابزارهای گزارش‌دهی که در این صفحه توضیح داده شده‌اند، همگی برای عملکرد Google Analytics نیاز دارند. اگر Google Analytics برای پروژه شما فعال نیست، می توانید آن را در تب ادغام تنظیمات پروژه Firebase خود تنظیم کنید.

به خاطر داشته باشید که گزارش بسیاری از آمارهای موجود در این صفحه به دلیل دسته‌بندی داده‌های تحلیلی تا 24 ساعت با تاخیر مواجه می‌شوند.

گزارش های تحویل پیام

در برگه گزارش‌ها در کنسول Firebase ، می‌توانید داده‌های زیر را برای پیام‌های ارسال شده به کیت‌های توسعه نرم‌افزاری FCM پلتفرم Android یا Apple، از جمله پیام‌هایی که از طریق سازنده Notifications و APIهای FCM ارسال می‌شوند، مشاهده کنید:

• ارسال می کند - پیام داده یا پیام اعلان برای تحویل در نوبت قرار گرفته است یا با موفقیت به یک سرویس شخص ثالث مانند APN ها برای تحویل ارسال شده است. برای اطلاعات بیشتر، طول عمر یک پیام را ببینید.
• دریافت شده (فقط در دستگاه های Android موجود است) - پیام داده یا پیام اعلان توسط برنامه دریافت شده است. این داده‌ها زمانی در دسترس هستند که دستگاه Android دریافت‌کننده FCM SDK 18.0.1 یا بالاتر را نصب کرده باشد.
• Impressions (فقط برای پیام‌های اعلان در دستگاه‌های Android موجود است) - در حالی که برنامه در پس‌زمینه است، اعلان نمایش روی دستگاه نمایش داده می‌شود.
• باز می شود - کاربر پیام اعلان را باز کرد. فقط برای اعلان‌های دریافتی زمانی که برنامه در پس‌زمینه است، گزارش می‌شود.

این داده برای همه پیام‌های دارای بار اعلان و همه پیام‌های داده برچسب‌دار در دسترس است. برای کسب اطلاعات بیشتر درباره برچسب‌ها، به افزودن برچسب‌های تحلیلی به پیام‌ها مراجعه کنید.

هنگام مشاهده گزارش‌های پیام، می‌توانید محدوده تاریخ را برای داده‌های نمایش داده شده با گزینه صادرات به CSV تنظیم کنید. همچنین می توانید با این معیارها فیلتر کنید:

• پلتفرم (iOS یا Android)
• برنامه
• برچسب های تجزیه و تحلیل سفارشی

افزودن برچسب های تحلیلی به پیام ها

برچسب گذاری پیام ها برای تجزیه و تحلیل سفارشی بسیار مفید است و به شما امکان می دهد آمار تحویل را بر اساس برچسب ها یا مجموعه ای از برچسب ها فیلتر کنید. می توانید با تنظیم فیلد fcmOptions.analyticsLabel در شیء پیام یا در فیلدهای AndroidFcmOptions یا ApnsFcmOptions مخصوص پلتفرم، به هر پیام ارسال شده از طریق API HTTP v1 یک برچسب اضافه کنید.

برچسب‌های تجزیه و تحلیل رشته‌های متنی با قالب ^[a-zA-Z0-9-_.~%]{1,50}$ هستند. برچسب ها می توانند شامل حروف کوچک و بزرگ، اعداد و نمادهای زیر باشند:

• -
• ~
• %

حداکثر طول 50 کاراکتر است. شما می توانید تا 100 برچسب منحصر به فرد در روز را مشخص کنید. پیام‌هایی با برچسب‌هایی که بیش از این حد اضافه شده گزارش نمی‌شوند.

در برگه گزارش‌های پیام‌رسانی کنسول Firebase ، می‌توانید فهرستی از تمام برچسب‌های موجود را جستجو کنید و آنها را به‌صورت جداگانه یا ترکیبی برای فیلتر کردن آمار نمایش داده شده اعمال کنید.

جمع آوری داده های تحویل از طریق FCM Data API

Firebase Cloud Messaging Data به شما امکان می‌دهد اطلاعاتی را بازیابی کنید که می‌تواند به شما در درک نتایج درخواست‌های پیام هدف‌گذاری شده برای برنامه‌های Android کمک کند. API داده‌های جمع‌آوری شده را در تمام دستگاه‌های 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 به وضوح نشان می‌دهد که شما از حداکثر محدودیت‌های هر دستگاه فراتر رفته‌اید و باید سرعت ارسال پیام‌ها را تنظیم کند.

درصد بینش پیام

این شی اطلاعات اضافی در مورد تمام پیام ارسال می کند. فیلد priorityLowered درصد پیام‌های پذیرفته‌شده را بیان می‌کند که اولویت آنها از HIGH به NORMAL کاهش یافته است. اگر این مقدار زیاد است، سعی کنید پیام‌های کمتری با اولویت بالا ارسال کنید یا اطمینان حاصل کنید که همیشه هنگام ارسال پیام با اولویت بالا، اعلان نمایش داده می‌شود. برای اطلاعات بیشتر به اسناد ما در مورد اولویت پیام مراجعه کنید

این داده ها چه تفاوتی با داده های صادر شده به BigQuery دارند؟

صادرات BigQuery گزارش‌های پیام فردی را در مورد پذیرش پیام توسط بخش پشتیبان FCM و تحویل پیام در SDK روی دستگاه ارائه می‌کند (مراحل 2 و 4 معماری FCM ). این داده ها برای اطمینان از پذیرش و تحویل پیام های فردی مفید است. در بخش بعدی درباره صادرات داده BigQuery بیشتر بخوانید.

در مقابل، Firebase Cloud Messaging Data API جزئیات انبوهی را در مورد آنچه به طور خاص در لایه حمل و نقل Android (یا مرحله 3 معماری FCM ) اتفاق می افتد ارائه می دهد. این داده‌ها به‌طور خاص بینشی درباره تحویل پیام‌ها از پشتیبان‌های FCM به Android SDK ارائه می‌دهند. این به ویژه برای نشان دادن روندهایی که چرا پیام ها در طول این حمل و نقل به تأخیر افتاده یا حذف شده اند مفید است.

در برخی موارد، ممکن است این دو مجموعه داده به دلیل موارد زیر دقیقاً مطابقت نداشته باشند:

• معیارهای جمع‌آوری شده تنها بخشی از همه پیام‌ها را نمونه‌برداری می‌کنند
• معیارهای جمع آوری گرد شده است
• ما معیارهایی را زیر آستانه حریم خصوصی ارائه نمی کنیم
• بخشی از پیامدهای پیام به دلیل بهینه‌سازی‌هایی که در نحوه مدیریت حجم زیادی از ترافیک انجام می‌شود وجود ندارد.

محدودیت های API

جدول زمانی داده های جمعی

API داده های تاریخی 7 روزه را برمی گرداند. با این حال، داده های بازگردانده شده توسط این API تا 5 روز به تاخیر می افتد. به عنوان مثال، در 20 ژانویه، داده های مربوط به 9 ژانویه تا 15 ژانویه در دسترس خواهد بود، اما نه برای 16 ژانویه یا بعد از آن. علاوه بر این، داده ها در بهترین تلاش ارائه می شوند. در صورت قطع اطلاعات، FCM برای رفع مشکل کار می کند و پس از رفع مشکل، داده ها را پر نمی کند. در قطعی های بزرگتر، داده ها ممکن است برای یک هفته یا بیشتر در دسترس نباشند.

پوشش داده ها

معیارهای ارائه شده توسط Firebase Cloud Messaging Data API به منظور ارائه بینشی در مورد روندهای گسترده تحویل پیام است. با این حال، آنها پوشش 100٪ همه سناریوهای پیام را ارائه نمی دهند. سناریوهای زیر نتایج شناخته شده ای هستند که در معیارها منعکس نشده اند.

پیام های منقضی شده

اگر زمان زندگی (TTL) پس از پایان تاریخ ثبت داده شده منقضی شود، پیام در این تاریخ به عنوان droppedTtlExpired محاسبه نخواهد شد.

پیام به دستگاه های غیرفعال

پیام‌های ارسال شده به دستگاه‌های غیرفعال ممکن است بسته به مسیر داده‌ای که طی می‌کنند، در مجموعه داده نشان داده شوند یا نشوند. این می تواند منجر به شمارش اشتباه در فیلدهای droppedDeviceInactive و pending .

پیام‌هایی به دستگاه‌هایی با تنظیمات خاص کاربر

کاربرانی که جمع‌آوری اطلاعات استفاده و تشخیصی را در دستگاه‌های خود غیرفعال کرده‌اند، با توجه به اولویت‌هایشان، پیام‌هایشان در شمارش ما لحاظ نخواهد شد.

گرد کردن و حداقل ها

FCM عمداً شمارش هایی را که حجم ها به اندازه کافی بزرگ نیستند، گرد می کند و حذف می کند.

صادرات داده BigQuery

می توانید داده های پیام خود را برای تجزیه و تحلیل بیشتر به BigQuery صادر کنید. BigQuery به شما امکان می‌دهد داده‌ها را با استفاده از BigQuery SQL تجزیه و تحلیل کنید، آن‌ها را به ارائه‌دهنده ابری دیگر صادر کنید یا از داده‌ها برای مدل‌های ML سفارشی خود استفاده کنید. صادرات به BigQuery شامل تمام داده‌های موجود برای پیام‌ها، صرف‌نظر از نوع پیام یا ارسال پیام از طریق API یا سازنده Notifications است.

برای پیام‌هایی که به دستگاه‌هایی با حداقل نسخه FCM SDK زیر ارسال می‌شوند، گزینه دیگری برای فعال کردن صادرات داده‌های تحویل پیام برای برنامه خود دارید:

• اندروید 20.1.0 یا بالاتر.
• iOS 8.6.0 یا بالاتر
• Firebase Web SDK 9.0.0 یا بالاتر

برای جزئیات بیشتر در مورد فعال کردن صادرات داده برای Android و iOS به زیر مراجعه کنید.

برای شروع، پروژه خود را به BigQuery پیوند دهید:

1. یکی از گزینه های زیر را انتخاب کنید:

   • Notifications composer را باز کنید، سپس روی Access 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 لغو کنید.

فعال کردن صادرات داده های تحویل پیام

دستگاه‌های Android با FCM SDK 20.1.0 یا بالاتر می‌توانند صادرات داده تحویل پیام برنامه خود را فعال کنند. صادرات داده به طور پیش فرض در سطح برنامه غیرفعال است. فعال کردن آن به صورت برنامه‌ای در سطح نمونه برنامه به شما امکان می‌دهد از کاربران نهایی برای تجزیه و تحلیل داده‌های تحویل پیام خود اجازه بخواهید (توصیه می‌شود). در جایی که هر دو تنظیم شده اند، مقدار سطح نمونه برنامه بر مقدار سطح برنامه لغو می شود.

قبل از فعال کردن این گزینه ها، ابتدا باید پیوند FCM -BiqQuery را برای پروژه خود همانطور که در صادرات داده BigQuery توضیح داده شده است ایجاد کنید.

فعال کردن صادرات داده های تحویل برای نمونه های برنامه

در بیشتر موارد، توصیه می‌کنیم که صادرات داده‌های تحویل پیام را فقط در سطح نمونه برنامه فعال کنید و آن را در سطح برنامه غیرفعال کنید.

 FirebaseMessaging.getInstance().setDeliveryMetricsExportToBigQuery(true)

فعال کردن صادرات داده های تحویل برای یک برنامه

اگر ترجیح می دهید صادرات را در سطح برنامه فعال کنید، مطمئن شوید که متد setDeliveryMetricsExportToBigQuery را فراخوانی نکنید و ویژگی زیر را به شی برنامه در مانیفست برنامه خود اضافه کنید:

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

چه داده هایی به 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>; .

مدت زمان fanout را برای یک موضوع یا کمپین معین محاسبه کنید

زمان شروع fanout زمانی است که درخواست اصلی دریافت می شود و زمان پایان زمانی است که آخرین پیام فردی که یک نمونه را هدف قرار می دهد ایجاد می شود.

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;