О сообщениях FCM

Firebase Cloud Messaging ( FCM ) предлагает широкий спектр возможностей и вариантов обмена сообщениями. Информация на этой странице поможет вам разобраться в различных типах сообщений FCM и их возможностях.

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

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

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

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

Вот сообщение в формате JSON, содержащее как ключ notification , так и ключ data :

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    },
    "data" : {
      "Nick" : "Mario",
      "Room" : "PortugalVSDenmark"
    }
  }
}

Варианты доставки

FCM предоставляет определённый набор параметров доставки сообщений, отправляемых на устройства Android, и допускает аналогичные возможности на платформах Apple и в веб-приложениях. Например, «сворачиваемое» поведение сообщений поддерживается на Android через функцию FCM collapse_key , на Apple — через apns-collapse-id , а на JavaScript/Web — через Topic . Подробнее см. описания в этом разделе и соответствующую справочную документацию.

Установка приоритета сообщения

Существует два варианта назначения приоритета доставки нижестоящим сообщениям: обычный и высокий. Хотя поведение немного различается на разных платформах, доставка сообщений с обычным и высоким приоритетом работает следующим образом:

• Обычный приоритет. Сообщения с обычным приоритетом доставляются немедленно, когда приложение находится на переднем плане. Для фоновых приложений доставка может быть задержана. Для менее срочных сообщений, таких как уведомления о новых письмах, синхронизация пользовательского интерфейса или синхронизация данных приложения в фоновом режиме, выберите обычный приоритет доставки.

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

При отправке сообщений с данными на устройства Apple приоритет должен быть установлен на 5, или на обычный. Сообщения, отправленные с высоким приоритетом, отклоняются бэкендом FCM с ошибкой INVALID_ARGUMENT .

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

{
  "message":{
    "topic":"subscriber-updates",
    "notification":{
      "body" : "This week's edition is now available.",
      "title" : "NewsMagazine.com",
    },
    "data" : {
      "volume" : "3.21.15",
      "contents" : "http://www.news-magazine.com/world-week/21659772"
    },
    "android":{
      "priority":"normal"
    },
    "apns":{
      "headers":{
        "apns-priority":"5"
      }
    },
    "webpush": {
      "headers": {
        "Urgency": "high"
      }
    }
  }
}

Более подробную информацию о настройке приоритета сообщений для конкретной платформы можно найти здесь:

• Документация APN
• Установка и управление приоритетом сообщений (Android)
• Срочность push-сообщений в Интернете

Критически важные случаи использования

API FCM не предназначены для экстренных оповещений или других видов деятельности с высоким уровнем риска, где использование или сбой API может привести к смерти, травмам или ущербу окружающей среде (например, эксплуатация ядерных объектов, управление воздушным движением или системы жизнеобеспечения). Любое такое использование прямо запрещено Разделом 4.a.7 Условий использования. Вы несёте исключительную ответственность за соответствие своего приложения Условиям и за любой ущерб, возникший в результате несоблюдения вами этих Условий. Google предоставляет API «как есть» и оставляет за собой право прекратить предоставление API, любой их части или функции, а также вашего доступа к ним по любой причине и в любое время без какой-либо ответственности или каких-либо обязательств перед вами или вашими пользователями.

Установка срока жизни сообщения

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

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

На Android и в Web/JavaScript можно указать максимальный срок жизни сообщения. Значение должно быть от 0 до 2 419 200 секунд (28 дней) и соответствует максимальному периоду времени, в течение которого FCM хранит сообщение и пытается его доставить. Для запросов без этого поля по умолчанию используется максимальный срок в четыре недели.

Вот некоторые возможные варианты использования этой функции:

• Входящие звонки по видеочату
• Истекающие пригласительные мероприятия
• Календарь событий

Ещё одно преимущество указания срока жизни сообщения заключается в том, что FCM не применяет сворачиваемое ограничение количества сообщений к сообщениям со значением времени жизни 0 секунд. FCM обеспечивает наилучшую обработку сообщений, которые должны быть доставлены «сейчас или никогда». Имейте в виду, что значение time_to_live 0 означает, что сообщения, которые не могут быть доставлены немедленно, отбрасываются. Однако, поскольку такие сообщения никогда не сохраняются, это обеспечивает наилучшую задержку для отправки уведомлений.

Вот пример запроса, включающего TTL:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    },
    "apns":{
      "headers":{
        "apns-expiration":"1604750400"
      }
    },
    "android":{
      "ttl":"4500s"
    },
    "webpush":{
      "headers":{
        "TTL":"4500"
      }
    }
  }
}

Время жизни сообщения

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

В лучшем случае, если устройство подключено к FCM , экран включен и нет ограничений по регулированию скорости, сообщение доставляется немедленно.

Если устройство подключено, но находится в режиме Doze, FCM сохраняет сообщение с низким приоритетом до тех пор, пока устройство не выйдет из режима Doze. Именно здесь играет роль флаг collapse_key : если сообщение с таким же ключом свертывания (и токеном регистрации) уже существует и ожидает доставки, старое сообщение удаляется, а новое занимает его место (то есть старое сообщение свертывается новым). Однако, если ключ свертывания не установлен, и новое, и старое сообщения сохраняются для последующей доставки.

Если устройство не подключено к FCM , сообщение хранится до установления соединения (с соблюдением правил ключа свертывания). После установления соединения FCM доставляет все ожидающие сообщения на устройство. Если устройство больше не подключается (например, после сброса настроек к заводским), сообщение в конечном итоге удаляется из хранилища FCM по истечении времени ожидания. Время ожидания по умолчанию составляет четыре недели, если не установлен флаг time_to_live .

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

Чтобы получить более подробную информацию о доставке сообщений на платформах Android или Apple, ознакомьтесь с панелью отчетности FCM , которая регистрирует количество отправленных и открытых сообщений на устройствах Apple и Android, а также данные о «показах» (уведомлениях, увиденных пользователями) для приложений Android.

На устройствах Android с включённым прямым каналом обмена сообщениями, если устройство не подключалось к FCM более месяца, FCM всё равно принимает сообщение, но сразу же его отклоняет. Если устройство подключается в течение четырёх недель с момента отправки последнего сообщения, ваш клиент получает обратный вызов onDeletedMessages() . После этого приложение может корректно обработать ситуацию, обычно запрашивая полную синхронизацию с сервером приложения.

Наконец, когда FCM пытается отправить сообщение на устройство, а приложение было удалено, FCM сразу же отбрасывает это сообщение и аннулирует регистрационный токен. Дальнейшие попытки отправить сообщение на это устройство приведут к ошибке NotRegistered .

Реквизиты для входа

В зависимости от того, какие функции FCM вы реализуете, вам могут потребоваться следующие учетные данные из вашего проекта Firebase:

Идентификатор проекта	Уникальный идентификатор вашего проекта Firebase, используемый в запросах к конечной точке HTTP FCM v1. Это значение доступно на панели настроек консоли Firebase .
Регистрационный токен	Уникальная строка токена, идентифицирующая каждый экземпляр клиентского приложения. Регистрационный токен требуется для обмена сообщениями между отдельными устройствами и группами устройств. Обратите внимание, что регистрационные токены должны храниться в секрете.
Идентификатор отправителя	Уникальное числовое значение, создаваемое при создании проекта Firebase и доступное на вкладке Cloud Messaging панели настроек консоли Firebase . Идентификатор отправителя используется для идентификации каждого отправителя, который может отправлять сообщения клиентскому приложению.
Токен доступа	Краткосрочный токен OAuth 2.0, который авторизует запросы к HTTP v1 API. Этот токен связан с учётной записью службы, принадлежащей вашему проекту Firebase. Чтобы создать и ротировать токены доступа, следуйте инструкциям в разделе Авторизация отправки запросов .