Понимание доставки сообщений

Для устранения текущих сбоев доставки сообщений воспользуйтесь инструментом устранения неполадок FCM и ознакомьтесь с этой записью в блоге, чтобы понять различные причины отсутствия сообщений. Вы также можете посетить панель мониторинга состояния FCM , чтобы узнать, есть ли какие-либо текущие сбои в работе сервиса, влияющие на работу FCM.

FCM также предоставляет три набора инструментов, которые помогут вам получить общее представление об успешности и стратегии обмена сообщениями:

• Отчеты о доставке сообщений консоли Firebase
• Агрегированные показатели доставки Android SDK из Firebase Cloud Messaging Data API
• Комплексный экспорт данных в Google BigQuery

Для экспорта данных BigQuery и вкладки «Отчёты» в консоли Firebase требуется Google Analytics . Если Google Analytics не включён в вашем проекте, вы можете настроить его на вкладке «Интеграции» в настройках проекта Firebase. Для работы функции «Агрегированные данные доставки Google Analytics не требуется.

Помните, что предоставление многих статистических данных на этой странице может осуществляться с задержкой до 24 часов из-за пакетной обработки аналитических данных.

Отчеты о доставке сообщений

На вкладке «Отчеты» в консоли Firebase вы можете просмотреть следующие данные о сообщениях, отправленных в SDK FCM для платформ Android или Apple, включая сообщения, отправленные через компоновщик уведомлений и API FCM:

• Отправки — сообщение с данными или уведомление поставлено в очередь на доставку или успешно передано стороннему сервису, например APNs, для доставки. Обратите внимание, что статистика отправок может отставать на пару часов. Подробнее см. в разделе «Время жизни сообщения» .
• Получено (доступно только на устройствах Android) — приложение получило сообщение с данными или уведомление. Эти данные доступны, если на принимающем устройстве Android установлен FCM SDK 18.0.1 или выше.
• Показы (доступно только для уведомлений на устройствах Android) — уведомление на дисплее было отображено на устройстве, пока приложение работало в фоновом режиме.
• Открывается — пользователь открыл уведомление. Учитывается только для уведомлений, полученных, когда приложение работает в фоновом режиме.

Эти данные доступны для всех сообщений с уведомительной нагрузкой и всех помеченных сообщений с данными . Подробнее о метках см. в разделе Добавление аналитических меток к сообщениям .

При просмотре отчётов по сообщениям вы можете задать диапазон дат для отображаемых данных с возможностью экспорта в CSV-файл. Также доступна фильтрация по следующим критериям:

• Платформа (iOS или Android)
• Приложение
• Пользовательские аналитические метки

Добавление аналитических меток к сообщениям

Маркировка сообщений очень полезна для пользовательского анализа, позволяя фильтровать статистику доставки по меткам или наборам меток. Вы можете добавить метку к любому сообщению, отправленному через HTTP v1 API, установив поле fcmOptions.analyticsLabel в объекте сообщения или в полях AndroidFcmOptions или ApnsFcmOptions , специфичных для платформы.

Метки аналитики представляют собой текстовые строки в формате ^[a-zA-Z0-9-_.~%]{1,50}$ . Метки могут содержать строчные и заглавные буквы, цифры и следующие символы:

• -
• ~
• %

Максимальная длина — 50 символов. Вы можете указать до 100 уникальных меток в день; сообщения с метками, добавленными сверх этого лимита, не учитываются.

На вкладке «Отчеты» сообщений консоли Firebase вы можете выполнить поиск по списку всех существующих меток и применить их по отдельности или в сочетании для фильтрации отображаемой статистики.

Агрегированные данные о доставке с использованием API данных FCM

API данных Firebase Cloud Messaging позволяет получать информацию, которая поможет вам понять результаты запросов сообщений, адресованных приложениям Android. API предоставляет агрегированные данные по всем устройствам Android, поддерживающим сбор данных, в проекте. Сюда входит информация о проценте сообщений, доставленных без задержки, а также о количестве сообщений, задержанных или потерянных на транспортном уровне Android . Анализ этих данных позволяет выявить общие тенденции в доставке сообщений и найти эффективные способы повышения производительности запросов на отправку. Информацию о доступности диапазонов дат в отчётах см. в разделе «Агрегированные временные шкалы данных» .

API предоставляет все данные, доступные для данного приложения. См. справочную документацию API .

Как разбиты данные?

Данные о доставке разбиты по приложению, дате и метке аналитики . Вызов API вернет данные для каждой комбинации даты, приложения и метки аналитики. Например, отдельный 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%.

Количество принятых сообщений

Единственный показатель, включенный в набор данных, — это количество сообщений, принятых FCM для доставки на устройства Android. Все процентные значения используют это значение в качестве знаменателя. Обратите внимание, что это количество не включает сообщения, адресованные пользователям, которые отключили сбор информации об использовании и диагностике на своих устройствах.

Проценты результатов сообщений

Поля, включённые в объект MessageOutcomePercents предоставляют информацию о результатах запросов сообщений. Все категории являются взаимоисключающими. Они могут ответить на такие вопросы, как «Доставляются ли мои сообщения?» и «Что является причиной потери сообщений?».

Например, высокое значение поля droppedTooManyPendingMessages может указывать на то, что экземпляры приложения получают объём несворачиваемых сообщений, превышающий лимит FCM в 100 ожидающих сообщений. Чтобы снизить эту проблему, убедитесь, что ваше приложение обрабатывает вызовы onDeletedMessages , и рассмотрите возможность отправки сворачиваемых сообщений. Аналогично, высокий процент droppedDeviceInactive может быть сигналом к обновлению токенов регистрации на сервере, удалению устаревших токенов и отписке от тем. Рекомендации по этой теме см. в разделе Управление токенами регистрации FCM .

Проценты эффективности доставки

Поля объекта DeliveryPerformancePercents содержат информацию об успешно доставленных сообщениях. Это может ответить на такие вопросы, как «Были ли мои сообщения с задержкой?» и «Почему сообщения задерживаются?». Например, высокое значение delayedMessageThrottled явно указывает на превышение максимального количества сообщений для каждого устройства и требует корректировки частоты отправки сообщений.

Процент понимания сообщения

Этот объект предоставляет дополнительную информацию обо всех отправленных сообщениях. Поле priorityLowered отображает процент принятых сообщений, приоритет которых был понижен с HIGH до NORMAL . Если это значение велико, попробуйте отправлять меньше сообщений с высоким приоритетом или убедитесь, что вы всегда отображаете уведомление при отправке сообщения с высоким приоритетом. Подробнее см. в нашей документации о приоритете сообщений.

Чем эти данные отличаются от данных, экспортированных в BigQuery?

Экспорт данных BigQuery предоставляет журналы отдельных сообщений о принятии сообщений бэкендом FCM и их доставке в SDK на устройстве (шаги 2 и 4 архитектуры FCM ). Эти данные полезны для обеспечения принятия и доставки отдельных сообщений. Подробнее об экспорте данных BigQuery читайте в следующем разделе.

В отличие от этого, API Firebase Cloud Messaging Data предоставляет агрегированную информацию о том, что происходит конкретно на транспортном уровне Android (или на третьем этапе архитектуры 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, экспортировать их в другой облачный сервис или использовать их в собственных моделях машинного обучения. Экспорт в BigQuery включает все доступные данные сообщений, независимо от их типа и способа отправки: через API или через компоновщик уведомлений.

Для сообщений, отправляемых на устройства со следующими минимальными версиями 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 для Cloud Messaging :

• Firebase экспортирует ваши данные в BigQuery . Обратите внимание, что первоначальное распространение данных для экспорта может занять до 48 часов.

  • Вы можете вручную запланировать заполнение данных за последние 30 дней.

• После создания набора данных его местоположение изменить нельзя, но вы можете скопировать его в другое место или вручную переместить (создать заново). Подробнее см. в разделе Изменение местоположения набора данных .

• Firebase настраивает регулярную синхронизацию данных из вашего проекта Firebase с BigQuery . Эти ежедневные операции экспорта начинаются в 4:00 утра по тихоокеанскому времени и обычно завершаются в течение 24 часов.

• По умолчанию все приложения в вашем проекте связаны с BigQuery , и любые приложения, которые вы позже добавляете в проект, автоматически связаны с BigQuery . Вы можете управлять тем, какие приложения отправляют данные .

Чтобы деактивировать экспорт BigQuery , отключите свой проект в консоли Firebase .

Включить экспорт данных о доставке сообщений

Устройства iOS с FCM SDK 8.6.0 или выше могут включить экспорт данных о доставке сообщений из своего приложения. FCM поддерживает экспорт данных как для оповещений, так и для фоновых уведомлений. Перед включением этих опций необходимо создать ссылку FCM -BiqQuery для вашего проекта, как описано в разделе «Экспорт данных BigQuery» .

Включить экспорт данных о доставке для оповещений

Поскольку только оповещения могут активировать расширения приложения службы уведомлений, необходимо добавить расширение службы уведомлений в приложение и вызывать этот API внутри расширения службы, чтобы включить отслеживание отображаемых сообщений. См. документацию 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

Если вы создаете запросы на отправку с использованием API HTTP v1, обязательно укажите mutable-content = 1 в объекте полезной нагрузки .

Включить экспорт данных о доставке для фоновых уведомлений

Для фоновых сообщений, полученных, когда приложение находится на переднем плане или в фоновом режиме, вы можете вызвать API экспорта данных внутри обработчика сообщений с данными основного приложения. Этот вызов необходимо выполнять для каждого полученного уведомления:

// 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;