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

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

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

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

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

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

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

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

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

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

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

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

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

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

• -
• ~
• %

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

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

Совокупные данные о доставке через FCM Data API

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

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

Свернутые сообщения

Сообщения, которые были свернуты другим сообщением, не отображаются в наборе данных.

Сообщения на неактивные устройства

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