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

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

• Отчеты о доставке сообщений консоли Firebase
• Совокупные показатели доставки Android SDK из API данных Firebase Cloud Messaging
• Комплексный экспорт данных в 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)
• Приложение
• Пользовательские метки аналитики

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

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

Ярлыки Google Аналитики представляют собой текстовые строки в формате ^[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 см. в разделе «Управление регистрационными токенами FCM .

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

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

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

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

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

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

Напротив, API данных облачных сообщений Firebase предоставляет агрегированные сведения о том, что происходит конкретно на транспортном уровне Android (или на этапе 3 архитектуры FCM ). Эти данные, в частности, дают представление о доставке сообщений из серверных частей FCM в Android SDK. Это особенно полезно для отображения тенденций относительно того, почему сообщения были задержаны или удалены во время этой транспортировки.

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

• Агрегированные показатели выбирают только часть всех сообщений.
• Агрегированные показатели округляются.
• Мы не предоставляем показатели ниже порога конфиденциальности.
• Часть результатов сообщений отсутствует из-за оптимизации управления большим объемом трафика.

Ограничения API

Сроки агрегирования данных

API вернет исторические данные за 7 дней; однако данные, возвращаемые этим API, будут задержаны на срок до 5 дней. Например, 20 января будут доступны данные за 9–15 января, но не за 16 января или позже. Кроме того, данные предоставляются в лучшем виде. В случае сбоя данных FCM примет меры для исправления ситуации и не будет заполнять данные повторно после устранения проблемы. В случае более крупных сбоев данные могут быть недоступны в течение недели или более.

Охват данных

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