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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

Типы сообщений

С помощью FCM вы можете отправлять клиентам два типа сообщений:

• Уведомительные сообщения, иногда называемые «отображаемыми сообщениями». Они обрабатываются FCM SDK автоматически.
• Сообщения с данными, которые обрабатываются клиентским приложением.

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

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

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

Уведомления

Для тестирования или для маркетинга и повторного вовлечения пользователей вы можете отправлять уведомления с помощью консоли Firebase . Консоль Firebase обеспечивает A/B-тестирование на основе аналитики, которое поможет вам уточнить и улучшить маркетинговые сообщения.

Чтобы программно отправлять сообщения уведомлений с помощью Admin SDK или протоколов FCM , установите ключ notification с необходимым предопределенным набором параметров «ключ-значение» для видимой пользователю части сообщения уведомления. Например, вот уведомление в формате JSON в приложении для обмена мгновенными сообщениями. Пользователь может ожидать увидеть сообщение с заголовком «Португалия против Дании» и текстом «Отличный матч!» на устройстве:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    }
  }
}

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

Полный список предопределенных ключей, доступных для создания сообщений уведомлений, см. в справочной документации по объектам уведомлений протокола HTTP v1.

Сообщения данных

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

Например, вот сообщение в формате JSON в том же приложении обмена мгновенными сообщениями, что и выше, где информация инкапсулирована в общий ключ data , и ожидается, что клиентское приложение будет интерпретировать содержимое:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    }
  }
}

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

Шифрование сообщений данных

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

Уведомительные сообщения с дополнительными полезными данными

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

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

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

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

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

Настройка сообщения на разных платформах

Firebase Admin SDK и HTTP-протокол FCM v1 позволяют вашим запросам сообщений устанавливать все поля, доступные в объекте message . Это включает в себя:

• общий набор полей, которые будут интерпретироваться всеми экземплярами приложения, получающими сообщение.
• наборы полей, зависящие от платформы, такие как AndroidConfig и WebpushConfig , интерпретируемые только экземплярами приложения, работающими на указанной платформе.

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

Когда использовать общие поля

Используйте общие поля, если вы:

• Таргетинг на экземпляры приложений на всех платформах — Apple, Android и в Интернете.
• Отправка сообщений в темы

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

• message.notification.title
• message.notification.body
• message.data

Когда использовать поля, специфичные для платформы

Используйте поля, специфичные для платформы, если вы хотите:

• Отправлять поля только на определенные платформы
• Отправляйте поля, специфичные для платформы , в дополнение к общим полям.

Если вы хотите отправлять значения только на определенные платформы, не используйте общие поля; используйте поля, специфичные для платформы. Например, чтобы отправить уведомление только на платформы Apple и в Интернет, но не на Android, необходимо использовать два отдельных набора полей: один для Apple и один для Интернета.

Когда вы отправляете сообщения с определенными параметрами доставки , используйте поля для конкретной платформы, чтобы установить их. Если хотите, вы можете указать разные значения для каждой платформы. Однако даже если вы хотите установить по существу одно и то же значение для разных платформ, вы должны использовать поля, специфичные для платформы. Это связано с тем, что каждая платформа может интерпретировать значение немного по-разному — например, срок жизни на Android устанавливается как срок действия в секундах, а на Apple — как дата истечения срока действия.

Пример: уведомление с вариантами доставки для конкретной платформы.

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

• устанавливает длительный срок жизни для Android и веб-платформ, одновременно устанавливая низкий приоритет сообщений APN (платформы Apple)
• задает соответствующие клавиши для определения результата нажатия пользователем на уведомление на Android и Apple — click_action и category соответственно.

{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"Match update",
       "body":"Arsenal goal in added time, score is now 3-0"
     },
     "android":{
       "ttl":"86400s",
       "notification"{
         "click_action":"OPEN_ACTIVITY_1"
       }
     },
     "apns": {
       "headers": {
         "apns-priority": "5",
       },
       "payload": {
         "aps": {
           "category": "NEW_MESSAGE_CATEGORY"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

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

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

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

Нескладные и сворачиваемые сообщения

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

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

Для Android существует ограничение в 100 сообщений, которые можно сохранить без свертывания. Если лимит достигнут, все сохраненные сообщения удаляются. Когда устройство снова подключается к сети, оно получает специальное сообщение о том, что лимит достигнут. Затем приложение может правильно обработать ситуацию, обычно запрашивая полную синхронизацию с сервера приложений.

Сворачиваемое сообщение — это сообщение, которое может быть заменено новым сообщением, если оно еще не доставлено на устройство.

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

Чтобы пометить сообщение как свертываемое на Android, включите параметр collapse_key в полезные данные сообщения. По умолчанию ключом свертывания является имя пакета приложения, зарегистрированное в консоли Firebase . Сервер FCM может одновременно хранить четыре разных свертываемых сообщения на одно устройство, каждое из которых имеет свой ключ свертывания. Если вы превысите это число, FCM сохранит только четыре ключа свертывания, без каких-либо гарантий относительно того, какие из них будут сохранены.

Тематические сообщения без полезной нагрузки по умолчанию сворачиваются. Сообщения уведомлений всегда сворачиваются и игнорируют параметр collapse_key .

Что мне следует использовать?

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

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

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

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

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

Вот пример сообщения с обычным приоритетом, отправляемого по протоколу 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)
• Срочность веб-пуш-сообщений

Жизненно важные случаи использования

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

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

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

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

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

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

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

Регулирование и квоты

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

Регулирование количества сообщений в нисходящем направлении

API HTTP v1 ввел поминутные квоты для каждого проекта для обмена сообщениями в нисходящем направлении. Квота по умолчанию в 600 тыс. сообщений в минуту охватывает более 99% разработчиков FCM , обеспечивая при этом стабильность системы и сводя к минимуму влияние нестандартных проектов.

Неравномерный трафик может привести к ошибкам превышения квоты. В случае превышения квоты система передает код состояния HTTP 429 (QUOTA_EXCEEDED) до тех пор, пока квота не будет пополнена в следующую минуту. Ответы 429 также могут возвращаться в ситуациях перегрузки, поэтому настоятельно рекомендуется обрабатывать сообщения 429 в соответствии с опубликованными рекомендациями .

Обратите внимание, что:

• Квота нисходящего потока измеряет сообщения, а не запросы.
• Ошибки клиента (код состояния HTTP 400–499) учитываются (исключая 429).
• Квоты указаны поминутно, но эти минуты не привязаны к часам.

Мониторинг квоты

Вы можете просмотреть квоту, использование и ошибки в Google Cloud Console:

1. Перейдите в консоль Google Cloud
2. Выберите API и сервисы
3. В списке таблиц выберите Firebase Cloud Messaging API .
4. Выберите КВОТА И СИСТЕМНЫЕ ОГРАНИЧЕНИЯ .

ПРИМЕЧАНИЕ. Эти графики не совсем привязаны по времени к минутам квоты. Это означает, что сообщения 429 могут обслуживаться, когда трафик оказывается ниже квоты.

Запрос на увеличение квоты

Прежде чем запрашивать увеличение квоты, убедитесь, что:

• Ваше использование регулярно составляет ≥ 80% от квоты в течение как минимум 5 минут подряд в день.
• У вас коэффициент ошибок клиента < 5%, особенно во время пикового трафика.
• Вы придерживаетесь лучших практик по отправке сообщений в больших масштабах .

Если вы соответствуете этим критериям, вы можете подать запрос на увеличение квоты на сумму до +25%, и FCM приложит все практические усилия для выполнения запроса (никакое увеличение не может быть гарантировано).

Если вам требуется дополнительная квота на обмен сообщениями в нисходящем направлении из-за предстоящего запуска или временного события, запросите квоту как минимум за 15 дней, чтобы у вас было достаточно времени для обработки запроса. Для больших запросов (>18 миллионов сообщений в минуту) требуется уведомление как минимум за 30 дней. Запуски и запросы на специальные мероприятия по-прежнему регулируются коэффициентом ошибок клиента и требованиями передового опыта.

См. также FAQ о квотах FCM .

Ограничение сообщений в теме

Скорость добавления/удаления подписки на тему ограничена 3000 QPS на проект.

Скорость отправки сообщений см. в разделе Fanout Throttling .

Регулирование разветвления

Разветвление сообщения — это процесс отправки сообщения на несколько устройств, например, когда вы ориентируетесь на темы и группы или когда вы используете композитор уведомлений для таргетинга на аудитории или сегменты пользователей.

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

Фактическая достижимая скорость разветвления зависит от количества проектов, запрашивающих разветвление одновременно. Скорость разветвления 10 000 QPS для отдельного проекта не является редкостью, но это число не является гарантией и является результатом общей нагрузки на систему. Важно отметить, что доступная емкость разветвления распределяется между проектами, а не между запросами на разветвление. Таким образом, если в вашем проекте выполняются два разветвления, то каждое разветвление будет видеть только половину доступной скорости разветвления. Рекомендуемый способ максимизировать скорость разветвления — одновременно иметь только одно активное разветвление.

Свертываемое регулирование сообщений

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

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

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

Мы ограничиваем количество сворачиваемых сообщений пакетом из 20 сообщений для каждого приложения на устройство с пополнением 1 сообщения каждые 3 минуты.

Максимальная скорость передачи сообщений на одно устройство

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

Для iOS мы возвращаем ошибку, когда скорость превышает ограничения APN.

Порты FCM и ваш брандмауэр

Если в вашей организации есть брандмауэр для ограничения трафика, входящего или исходящего из Интернета, вам необходимо настроить его, чтобы разрешить мобильным устройствам подключаться к FCM , чтобы устройства в вашей сети могли получать сообщения. FCM обычно использует порт 5228, но иногда использует порты 443, 5229 и 5230.

Для устройств, подключающихся к вашей сети, FCM не предоставляет конкретные IP-адреса, поскольку наш диапазон IP-адресов меняется слишком часто, и правила вашего брандмауэра могут устареть, что повлияет на удобство работы ваших пользователей. В идеале порты 5228-5230 и 443 должны быть включены в белый список без ограничений по IP. Однако если вам необходимо установить ограничение по IP-адресам, вам следует внести в список разрешенных все IP-адреса, перечисленные в goog.json . Этот большой список регулярно обновляется, и вам рекомендуется обновлять правила ежемесячно. Проблемы, вызванные ограничениями IP-адресов межсетевого экрана, часто носят непостоянный характер и их трудно диагностировать.

Мы предлагаем набор доменных имен, которые можно внести в белый список вместо IP-адресов. Эти имена хостов перечислены ниже. Если мы начнем использовать дополнительные имена хостов, мы обновим список здесь. Использование доменных имен для правила брандмауэра может работать или не работать на вашем устройстве брандмауэра.

TCP-порты, которые нужно открыть:

• 5228
• 5229
• 5230
• 443

Имена хостов для открытия:

• mtalk.google.com
• mtalk4.google.com
• mtalk-staging.google.com
• mtalk-dev.google.com
• alt1-mtalk.google.com
• alt2-mtalk.google.com
• alt3-mtalk.google.com
• alt4-mtalk.google.com
• alt5-mtalk.google.com
• alt6-mtalk.google.com
• alt7-mtalk.google.com
• alt8-mtalk.google.com
• android.apis.google.com
• устройство-provisioning.googleapis.com
• firebaseinstallations.googleapis.com

Межсетевые экраны трансляции сетевых адресов и/или проверки пакетов с отслеживанием состояния:

Если в вашей сети реализована трансляция сетевых адресов (NAT) или проверка пакетов с отслеживанием состояния (SPI), установите тайм-аут 30 минут или больше для наших подключений через порты 5228–5230. Это позволяет нам обеспечивать надежную связь, одновременно снижая расход заряда батареи мобильных устройств ваших пользователей.

VPN-взаимодействия и обходимость

Firebase Cloud Messaging предпринимает различные шаги, чтобы обеспечить надежность и доступность соединения push-сообщений с телефона на сервер как можно чаще. Использование VPN усложняет эту задачу.

VPN маскируют основную информацию, необходимую FCM для настройки соединения, чтобы максимизировать надежность и продлить срок службы батареи. В некоторых случаях VPN активно разрывают долгоживущие соединения, что приводит к ухудшению пользовательского опыта из-за пропущенных или задержанных сообщений или высокого расхода батареи. Когда VPN настроен так, чтобы мы могли это сделать, мы обходим VPN, используя зашифрованное соединение (через базовую сеть Wi-Fi или LTE), чтобы обеспечить надежную работу с экономией заряда батареи. Использование FCM обходных VPN специфично для канала push-уведомлений FCM . Другой трафик FCM , например трафик регистрации, использует VPN, если он активен. Когда соединение FCM обходит VPN, оно теряет дополнительные преимущества, которые может предоставить VPN, например маскирование IP-адреса.

Разные VPN будут иметь разные методы контроля возможности обхода сети. Инструкции см. в документации вашего конкретного VPN.

Если VPN не настроен для обхода, Firebase Cloud Messaging будет использовать сеть VPN для подключения к серверу. Это может привести к задержкам сообщений и увеличению расхода заряда батареи, поскольку Cloud Messaging поддерживает соединение через VPN-соединение.

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

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

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

Типы сообщений

С помощью FCM вы можете отправлять клиентам два типа сообщений:

• Уведомительные сообщения, иногда называемые «отображаемыми сообщениями». Они обрабатываются FCM SDK автоматически.
• Сообщения с данными, которые обрабатываются клиентским приложением.

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

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

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

Уведомления

Для тестирования или для маркетинга и повторного вовлечения пользователей вы можете отправлять уведомления с помощью консоли Firebase . Консоль Firebase обеспечивает A/B-тестирование на основе аналитики, которое поможет вам уточнить и улучшить маркетинговые сообщения.

Чтобы программно отправлять сообщения уведомлений с помощью Admin SDK или протоколов FCM , установите ключ notification с необходимым предопределенным набором параметров «ключ-значение» для видимой пользователю части сообщения уведомления. Например, вот уведомление в формате JSON в приложении для обмена мгновенными сообщениями. Пользователь может ожидать увидеть сообщение с заголовком «Португалия против Дании» и текстом «Отличный матч!» на устройстве:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    }
  }
}

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

Полный список предопределенных ключей, доступных для создания сообщений уведомлений, см. в справочной документации по объектам уведомлений протокола HTTP v1.

Сообщения данных

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

Например, здесь есть сообщение, форматированное JSON, в том же приложении IM, что и выше, где информация инкапсулируется в общий ключ data , и ожидается, что клиентское приложение будет интерпретировать контент:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    }
  }
}

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

Шифрование для сообщений данных

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

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

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

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

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

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

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

Настройка сообщения по платформам

Firebase Admin SDK и протокол FCM V1 HTTP позволяют вашему сообщению устанавливать все поля, доступные в объекте message . Это включает в себя:

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

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

Когда использовать общие поля

Используйте общие поля, когда вы:

• Нацеливание на экземпляры приложений на всех платформах - Apple, Android и Web
• Отправка сообщений на темы

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

• message.notification.title
• message.notification.body
• message.data

Когда использовать поля для конкретных платформ

Используйте поля, специфичные для платформы, когда вы хотите:

• Отправить поля только на определенные платформы
• Отправить поля для конкретной платформы в дополнение к общим полям

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

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

Пример: Сообщение уведомлений с параметрами доставки, специфичных для платформы,

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

• Устанавливает долгое время для Android и веб-платформ, одновременно устанавливая приоритет сообщения APNS (Apple Platforms) для низкой настройки
• Устанавливает соответствующие ключи, чтобы определить результат пользователя, нажимая на уведомление на Android и Apple - click_action и category соответственно.

{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"Match update",
       "body":"Arsenal goal in added time, score is now 3-0"
     },
     "android":{
       "ttl":"86400s",
       "notification"{
         "click_action":"OPEN_ACTIVITY_1"
       }
     },
     "apns": {
       "headers": {
         "apns-priority": "5",
       },
       "payload": {
         "aps": {
           "category": "NEW_MESSAGE_CATEGORY"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

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

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

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

Невозможные и складные сообщения

Неполосное сообщение обозначает, что каждое отдельное сообщение доставляется на устройство. Неполосное сообщение доставляет некоторый полезный контент, в отличие от складного сообщения, например, без контента «Ping» для мобильного приложения, чтобы связаться с сервером, чтобы получить данные.

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

Для Android существует предел из 100 сообщений, которые можно хранить без обрушения. Если ограничен достигнут, все сохраненные сообщения отбрасываются. Когда устройство вернется в Интернете, оно получает специальное сообщение, указывающее, что предел был достигнут. Затем приложение может правильно обрабатывать ситуацию, обычно запрашивая полную синхронизацию на сервере приложений.

Совместное сообщение - это сообщение, которое может быть заменено новым сообщением, если оно еще не доставлено на устройство.

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

Чтобы отметить сообщение как складное на Android, включите параметр collapse_key в полезную нагрузку сообщения. По умолчанию ключ коллапса - это имя пакета приложений, зарегистрированное в консоли Firebase . Сервер FCM может одновременно хранить четыре различных складных сообщения на устройство, каждое из которых имеет различный ключ коллапса. Если вы превышаете это число, FCM сохраняет только четыре клавиша обрушения, без гарантий о том, какие из них хранятся.

Тематические сообщения без полезной нагрузки по умолчанию не совпадают. Сообщения уведомлений всегда складываются и игнорируют параметр collapse_key .

Что мне использовать?

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

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

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

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

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

Вот пример обычного приоритетного сообщения, отправленного через протокол 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"
      }
    }
  }
}

Для получения дополнительной информации о платформе для установки приоритета сообщения:

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

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

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

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

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

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

На Android и Web/JavaScript вы можете указать максимальную продолжительность жизни сообщения. Значение должно составлять от 0 до 2419 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 сохраняется с низким приоритетом сообщением, пока устройство не выйдет из дока. И именно здесь флаг collapse_key играет роль: если уже есть сообщение с тем же ключом коллапса (и токеном регистрации), хранящимися и ожиданием доставки, старое сообщение отбрасывается, и новое сообщение занимает свое место (то есть старое сообщение обрушивается новым). Однако, если ключ коллапса не установлен, как новые, так и старые сообщения хранятся для будущей доставки.

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

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

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

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

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

Дросселя и квоты

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

Вниз по течению сообщения дросселирование

API HTTP V1 вводил квоты на предварительные квоты для обмена сообщениями вниз. Квота по умолчанию в размере 600 тыс. Сообщений в минуту охватывает более 99% разработчиков FCM , защищая стабильность системы и сводит к минимуму воздействие колючих проектов.

Колючие шаблоны трафика могут привести к тому, что квота превышает ошибки. В сценарии квот система служит коду состояния HTTP 429 (QUATA_EXEDED) до тех пор, пока квота не будет заполнена в следующую минуту. 429 ответов также могут быть возвращены в ситуациях перегрузки, поэтому вам настоятельно рекомендуется обрабатывать 429s в соответствии с опубликованными рекомендациями .

Обратите внимание, что:

• Нисходящая квота измеряет сообщения, а не запросы.
• Клиентские ошибки (HTTP Code 400-499) подсчитаны (исключая 429 с).
• Квоты на минуту, но эти минуты не выровнены по часам.

Квота мониторинга

Вы можете просматривать квоту, использование и ошибки на консоли Google Cloud:

1. Перейти в консоли Google Cloud
2. Выберите API и сервисы
3. В списке таблиц выберите API обмена обменами обмена Firebase API
4. Выберите ограничения квоты и системы .

ПРИМЕЧАНИЕ. Эти графики не имеют точности времени, выровненного с квотой, то есть 429s может быть подан, когда трафик, по -видимому, находится ниже квоты.

Запрашивая увеличение квоты

Прежде чем запросить увеличение квоты, убедитесь, что:

• Ваше использование регулярно ≥ 80% квоты в течение не менее 5 минут подряд в день.
• У вас есть <5% коэффициент ошибок клиента, особенно во время пикового трафика.
• Вы придерживаетесь лучших практик отправки сообщений в масштабе .

Если вы соответствуете этим критериям, вы можете подать запрос на увеличение квоты до +25%, а FCM приложит все практические усилия для выполнения запроса (увеличение не может быть гарантировано).

Если вам нужна дополнительная квота вниз по течению сообщений из -за надвигающегося запуска или временного события, запросите квоту, по крайней мере, за 15 дней, чтобы разрешить достаточное время для обработки запроса. Для больших запросов (> 18 метров сообщений в минуту) требуется не менее 30 дней уведомления. Запуск и специальные запросы на события по -прежнему подлежат коэффициенту ошибок клиента и требованиям к лучшим практикам.

См. Также FAQ о квотах FCM .

Предел тематического сообщения

Скорость добавления/удаления темы Add/удаление ограничена 3000 QP за проект.

Для отправки сообщений см. Fanout Throttling .

Фаньут дросселя

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

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

На фактическую достижимую скорость фаната влияет количество проектов, запрашивающих развлечения одновременно. Скорость фаната в 10 000 QP для отдельного проекта не является редкостью, но это число не является гарантией и является результатом общей нагрузки на систему. Важно отметить, что доступная емкость фанаута делится между проектами, а не на запросы на фанату. Таким образом, если в вашем проекте находится два фаната, то каждый фанат увидит только половину доступной ставки фанату. Рекомендуемый способ максимизировать скорость вашей фанаты состоит в том, чтобы иметь только один активный фанат за раз.

Складываемое сообщение дросселирование

Как описано выше, складываемые сообщения-это без контента уведомления, предназначенные для разрушения друг на друга. В случае, если разработчик слишком часто повторяет одно и то же сообщение в приложение, мы откладываем (дроссельные) сообщения, чтобы уменьшить влияние на батарею пользователя.

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

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

Мы ограничиваем складные сообщения до 20 сообщений на приложение на устройство, с пополнением 1 сообщений каждые 3 минуты.

Максимальная скорость сообщений на одно устройство

Для Android вы можете отправить до 240 сообщений/минуты и 5000 сообщений/час на одно устройство. Этот высокий порог предназначен для обеспечения краткосрочных всплесков трафика, например, когда пользователи быстро взаимодействуют по чату. Этот предел предотвращает ошибки при отправке логики от непреднамеренного истощения батареи на устройстве.

Для iOS мы возвращаем ошибку, когда скорость превышает ограничения APNS.

Порты FCM и ваш брандмауэр

Если в вашей организации есть брандмауэр для ограничения трафика в Интернет или из Интернета, вам необходимо настроить его, чтобы мобильные устройства могли соединиться с FCM , чтобы устройства в вашей сети получали сообщения. FCM обычно использует порт 5228, но иногда он использует 443, 5229 и 5230.

Для устройств, подходящих в вашей сети, FCM не предоставляет конкретные IPS, потому что наш диапазон IP слишком часто изменяется, а правила вашего брандмауэра могут устареться, влияя на опыт ваших пользователей. В идеале, порты AllistList 5228-5230 и 443 без ограничений IP. Однако, если у вас должно быть ограничение IP, вы должны разрешить список всех IP -адресов, перечисленных на Goog.json . Этот большой список регулярно обновляется, и вам рекомендуется ежемесячно обновлять свои правила. Проблемы, вызванные ограничениями IP брандмауэра, часто перемещаются и трудно диагностировать.

Мы предлагаем набор доменных имен, которые можно разрешить, а не IP -адреса. Эти имена хостов перечислены ниже. Если мы начнем использовать дополнительные имена хостов, мы обновим список здесь. Использование доменных имен для правила брандмауэра может быть или не быть функциональным в вашем устройстве брандмауэра.

Порты TCP для открытия:

• 5228
• 5229
• 5230
• 443

Имена хостов, чтобы открыть:

• mtalk.google.com
• mtalk4.google.com
• mtalk-staging.google.com
• mtalk-dev.google.com
• alt1-mtalk.google.com
• alt2-mtalk.google.com
• alt3-mtalk.google.com
• alt4-mtalk.google.com
• alt5-mtalk.google.com
• alt6-mtalk.google.com
• alt7-mtalk.google.com
• alt8-mtalk.google.com
• Android.apis.google.com
• Device-Provisioning.googleApis.com
• firebaseinstallations.googleapis.com

Перевод сетевого адреса и/или государственные брандмауэры пакетов:

Если ваша сеть реализует перевод сетевого адреса (NAT) или проверку пакетов с состоянием (SPI), реализуйте 30-минутный тайм-аут для наших подключений по портам 5228-5230. Это позволяет нам обеспечить надежное соединение при одновременном снижении потребления батареи мобильных устройств ваших пользователей.

VPN взаимодействия и обход

Firebase Cloud Messaging предпринимает различные шаги для обеспечения того, чтобы подключение к обмену сообщениями от телефона к серверу было надежным и доступно как можно чаще. Использование VPN усложняет это усилие.

VPNS маскирует базовую информацию, которую FCM должна настроить его соединение, чтобы максимизировать надежность и срок службы батареи. В некоторых случаях VPN активно нарушают долгосрочные подключения, что приводит к плохому опыту пользователя из -за пропущенных или отсроченных сообщений или высокой стоимости батареи. Когда VPN настроен, чтобы позволить нам это сделать, мы обходим VPN, используя зашифрованное соединение (через базовую сеть Wi -Fi или LTE), чтобы обеспечить надежный, дружественный для батареи опыт. Использование FCM обходных VPNS специфично для канала уведомления FCM Push. Другой трафик FCM , такой как регистрационный трафик, использует VPN, если он активен. Когда соединение FCM обходит VPN, он теряет дополнительные преимущества, которые может предоставить VPN, например, маскирование IP.

Различные VPN будут иметь разные методы для контроля, можно ли его обойти. Проконсультируйтесь с документацией для вашего конкретного VPN для инструкций.

Если VPN не настроен на то, чтобы быть обойдящимся, то Firebase Cloud Messaging будет использовать VPN -сеть для подключения к серверу. Это может привести к периодам времени, когда сообщения откладываются и могут привести к большему использованию батареи, поскольку Cloud Messaging работает над поддержанием соединения через соединение VPN.

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

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

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

Типы сообщений

С FCM вы можете отправить два типа сообщений клиентам:

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

Сообщения уведомлений содержат предварительно определенный набор видимых пользовательских ключей. Сообщения данных, напротив, содержат только пользовательские пользовательские пары клавиш. Сообщения уведомлений могут содержать дополнительную полезную нагрузку данных. Максимальная полезная нагрузка для обоих типов сообщений составляет 4096 байтов, за исключением случаев отправки сообщений из консоли Firebase , которая обеспечивает соблюдение лимита символа 1000.

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

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

Сообщения уведомления

Для тестирования или для маркетинга и повторного внедрения пользователей вы можете отправлять сообщения уведомлений с помощью консоли Firebase . Консоль Firebase предоставляет A/B-тестирование на основе аналитики, чтобы помочь вам уточнить и улучшить маркетинговые сообщения.

Чтобы программно отправлять сообщения уведомлений с использованием Admin SDK или протоколов FCM , установите ключ notification с необходимым предопределенным набором параметров клавиш для видимой пользователя части сообщения об уведомлении. Например, вот сообщение уведомлений, форматированного JSON, в приложении IM. Пользователь может ожидать увидеть сообщение с заголовком «Португалия против Дании» и текст «Отличный матч!» На устройстве:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    }
  }
}

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

См. Справочная документация объекта уведомления о протоколе HTTP V1 для полного списка предопределенных ключей, доступных для сообщений по созданию уведомлений.

Сообщения данных

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

Например, здесь есть сообщение, форматированное JSON, в том же приложении IM, что и выше, где информация инкапсулируется в общий ключ data , и ожидается, что клиентское приложение будет интерпретировать контент:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    }
  }
}

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

Шифрование для сообщений данных

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

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

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

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

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

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

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

Настройка сообщения по платформам

Firebase Admin SDK и протокол FCM V1 HTTP позволяют вашему сообщению устанавливать все поля, доступные в объекте message . Это включает в себя:

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

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

Когда использовать общие поля

Используйте общие поля, когда вы:

• Нацеливание на экземпляры приложений на всех платформах - Apple, Android и Web
• Отправка сообщений на темы

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

• message.notification.title
• message.notification.body
• message.data

Когда использовать поля для конкретных платформ

Используйте поля, специфичные для платформы, когда вы хотите:

• Отправить поля только на определенные платформы
• Отправить поля для конкретной платформы в дополнение к общим полям

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

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

Example: notification message with platform-specific delivery options

The following v1 send request sends a common notification title and content to all platforms, but also sends some platform-specific overrides. Specifically, the request:

• sets a long time-to-live for Android and Web platforms, while setting the APNs (Apple platforms) message priority to a low setting
• sets the appropriate keys to define the result of a user tap on the notification on Android and Apple — click_action , and category , respectively.

{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"Match update",
       "body":"Arsenal goal in added time, score is now 3-0"
     },
     "android":{
       "ttl":"86400s",
       "notification"{
         "click_action":"OPEN_ACTIVITY_1"
       }
     },
     "apns": {
       "headers": {
         "apns-priority": "5",
       },
       "payload": {
         "aps": {
           "category": "NEW_MESSAGE_CATEGORY"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

See the HTTP v1 reference documentation for complete detail on the keys available in platform-specific blocks in the message body. For more information about building send requests that contain the message body, see Build Send Requests .

Delivery options

FCM provides a specific set of delivery options for messages sent to Android devices, and allows for similar options on Apple platforms and web. For example, "collapsible" message behavior is supported on Android via FCM 's collapse_key , on Apple via apns-collapse-id , and on JavaScript/Web via Topic . For details, see descriptions in this section and related reference documentation.

Non-collapsible and collapsible messages

A non-collapsible message denotes that each individual message is delivered to the device. A non-collapsible message delivers some useful content, as opposed to a collapsible message like a content-free "ping" to the mobile app to contact the server to fetch data.

Some typical use cases of non-collapsible messages are chat messages or critical messages. For example, in an IM app, you would want to deliver every message, because every message has different content.

For Android there is a limit of 100 messages that can be stored without collapsing. If the limit is reached, all stored messages are discarded. When the device is back online, it receives a special message indicating that the limit was reached. The app can then handle the situation properly, typically by requesting a full sync from the app server.

A collapsible message is a message that may be replaced by a new message if it has yet to be delivered to the device.

A common use cases of collapsible messages are messages used to tell a mobile app to sync data from the server. An example would be a sports app that updates users with the latest score. Only the most recent message is relevant.

To mark a message as collapsible on Android, include the collapse_key parameter in the message payload. By default, the collapse key is the app package name registered in the Firebase console. The FCM server can simultaneously store four different collapsible messages per device, each with a different collapse key. If you exceed this number, FCM only keeps four collapse keys, with no guarantees about which ones are kept.

Topic messages with no payload are collapsible by default. Notification messages are always collapsible and will ignore the collapse_key parameter.

Which should I use?

Collapsible messages are a better choice from a performance standpoint, provided your app doesn't need to use non-collapsible messages. However, if you use collapsible messages, remember that FCM only allows a maximum of four different collapse keys to be used by FCM per registration token at any given time. You must not exceed this number, or it could cause unpredictable consequences.

Setting the priority of a message

You have two options for assigning delivery priority to downstream messages: normal and high priority. Though the behavior differs slightly across platforms, delivery of normal and high priority messages works like this:

• Normal priority. Normal priority messages are delivered immediately when the app is in the foreground. For backgrounded apps, delivery may be delayed. For less time-sensitive messages, such as notifications of new email, keeping your UI in sync, or syncing app data in the background, choose normal delivery priority.

• High priority. FCM attempts to deliver high priority messages immediately even if the device is in Doze mode. High priority messages are for time-sensitive, user visible content.

Here is an example of a normal priority message sent via the FCM HTTP v1 protocol to notify a magazine subscriber that new content is available to download:

{
  "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"
      }
    }
  }
}

For more platform-specific detail on setting message priority:

• APNs documentation
• Set and manage message priority (Android)
• Web push message urgency

Life critical use cases

The FCM APIs are not designed for emergency alerts or other high-risk activities where the use or failure of the APIs could result in death, personal injury, or environmental damage (such as the operation of nuclear facilities, air traffic control, or life support systems). Any such use is expressly prohibited under Section 4. a. 7 of the Terms of Service. You are solely responsible for managing your app's compliance with the Terms, and any damages resulting from your noncompliance. Google provides the APIs "as is," and reserves the right to discontinue the APIs or any portion or feature or your access thereto, for any reason and at any time, without liability or other obligation to you or your users.

Setting the lifespan of a message

FCM usually delivers messages immediately after they are sent. However, this might not always be possible. For example, if the platform is Android, the device could be turned off, offline, or otherwise unavailable. Or FCM might intentionally delay messages to prevent an app from consuming excessive resources and negatively affecting battery life.

When this happens, FCM stores the message and delivers it as soon as it's feasible. While this is fine in most cases, there are some apps for which a late message might as well never be delivered. For example, if the message is an incoming call or video chat notification, it is meaningful only for a short period of time before the call is terminated. Or if the message is an invitation to an event, it is useless if received after the event has ended.

On Android and Web/JavaScript, you can specify the maximum lifespan of a message. The value must be a duration from 0 to 2,419,200 seconds (28 days), and it corresponds to the maximum period of time for which FCM stores and attempts to deliver the message. Requests that don't contain this field default to the maximum period of four weeks.

Here are some possible uses for this feature:

• Video chat incoming calls
• Expiring invitation events
• Calendar events

Another advantage of specifying the lifespan of a message is that FCM doesn't apply collapsible message throttling to messages with a time-to-live value of 0 seconds. FCM provides best effort handling of messages that must be delivered "now or never." Keep in mind that a time_to_live value of 0 means messages that can't be delivered immediately are discarded. However, because such messages are never stored, this provides the best latency for sending notification messages.

Here is an example of a request that includes 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"
      }
    }
  }
}

Lifetime of a message

When an app server posts a message to FCM and receives a message ID back, it does not mean that the message was already delivered to the device. Rather, it means that it was accepted for delivery. What happens to the message after it is accepted depends on many factors.

In the best-case scenario, if the device is connected to FCM , the screen is on and there are no throttling restrictions, the message is delivered right away.

If the device is connected but in Doze, a low priority message is stored by FCM until the device is out of Doze. And that's where the collapse_key flag plays a role: if there is already a message with the same collapse key (and registration token) stored and waiting for delivery, the old message is discarded and the new message takes its place (that is, the old message is collapsed by the new one). However, if the collapse key is not set, both the new and old messages are stored for future delivery.

If the device is not connected to FCM , the message is stored until a connection is established (again respecting the collapse key rules). When a connection is established, FCM delivers all pending messages to the device. If the device never gets connected again (for instance, if it was factory reset), the message eventually times out and is discarded from FCM storage. The default timeout is four weeks, unless the time_to_live flag is set.

To get more insight into the delivery of a message:

To get more insight into the delivery of messages on Android or Apple platforms, see the FCM reporting dashboard , which records the number of messages sent and opened on Apple and Android devices, along with data for "impressions" (notifications seen by users) for Android apps.

For Android devices with direct channel messaging enabled, if the device has not connected to FCM for more than one month, FCM still accepts the message but immediately discards it. If the device connects within four weeks of the last data message you sent to it, your client receives the onDeletedMessages() callback. The app can then handle the situation properly, typically by requesting a full sync from the app server.

Finally, when FCM attempts to deliver a message to the device and the app was uninstalled, FCM discards that message right away and invalidates the registration token. Future attempts to send a message to that device results in a NotRegistered error.

Throttling and quotas

Our goal is to always deliver every message sent via FCM. However, delivering every message sometimes results in a poor overall user experience. In other cases, we need to provide boundaries to ensure that FCM provides a scalable service for all senders. The types of limits and quotas described in this section help us balance these important factors.

Downstream message throttling

The HTTP v1 API introduced per-project, per-minute quotas for downstream messaging. The default quota of 600k messages per minute covers over 99% of FCM developers while protecting the stability of the system and minimizing the impact of spiky projects.

Spiky traffic patterns can result in quota exceeded errors. In an over quota scenario, the system serves HTTP status code 429 (QUOTA_EXCEEDED) until the quota is refilled in the following minute. 429 responses may also be returned in overload situations, so you are strongly encouraged to handle 429s according to published recommendations .

Обратите внимание, что:

• The downstream quota measures messages, not requests.
• Client errors (HTTP status code 400-499) are counted (excluding 429s).
• Quotas are per-minute, but these minutes are not aligned to the clock.

Monitoring quota

You can view quota, usage, and errors on the Google Cloud Console:

1. Go to the Google Cloud console
2. Select APIs & services
3. From the table list, select Firebase Cloud Messaging API
4. Select QUOTA & SYSTEM LIMITS .

NOTE: These graphs are not precisely time aligned with quota minutes, meaning 429s may be served when traffic appears to be below quota.

Requesting a quota increase

Before requesting a quota increase, ensure that:

• Your usage is regularly ≥ 80% of quota for at least 5 consecutive minutes per day.
• You have < 5% client error ratio, especially during peak traffic.
• You adhere to the best practices for sending messages at scale .

If you meet these criteria, you can submit a quota increase request for up to +25% and FCM will make every practical effort to fulfill the request (no increase can be guaranteed).

If you need more downstream messaging quota due to an impending launch or temporary event, request your quota at least 15 days in advance to allow sufficient time to handle the request. For large requests (>18M messages per minute), at least 30 days of notice is required. Launches and special event requests are still subject to the client error ratio and best practices requirements.

See also the FAQ about FCM quotas .

Topic message limit

The topic subscription add/remove rate is limited to 3,000 QPS per project.

For message sending rates, see Fanout Throttling .

Fanout throttling

Message fanout is the process of sending a message to multiple devices, such as when you target topics and groups, or when you use the Notifications composer to target audiences or user segments.

Message fanout is not instantaneous and so occasionally you have multiple fanouts in progress concurrently. We limit the number of concurrent message fanouts per project to 1,000. After that, we may reject additional fanout requests or defer the fanout of the requests until some of the already in progress fanouts complete.

The actual achievable fanout rate is influenced by the number of projects requesting fanouts at the same time. A fanout rate of 10,000 QPS for an individual project is not uncommon, but that number is not a guarantee and is a result of the total load on the system. It is important to note that the available fanout capacity is divided among projects and not across fanout requests. So, if your project has two fanouts in progress, then each fanout will only see half of the available fanout rate. The recommended way to maximize your fanout speed is to only have one active fanout in progress at a time.

Collapsible message throttling

As described above, collapsible messages are content-free notifications designed to collapse on top of each other. In the event that a developer is repeating the same message to an app too frequently, we delay (throttle) messages to reduce the impact on a user's battery.

For example, if you send large numbers of new email sync requests to a single device, we might delay the next email sync request a few minutes so that the device can sync at a lower average rate. This throttling is done strictly to limit the battery impact experienced by the user.

If your use case requires high burst send patterns, then non-collapsible messages may be the right choice. For such messages, make sure to include the content in such messages in order to reduce the battery cost.

We limit collapsible messages to a burst of 20 messages per app per device, with a refill of 1 message every 3 minutes.

Maximum message rate to a single device

For Android, you can send up to 240 messages/minute and 5,000 messages/hour to a single device. This high threshold is meant to allow for short term bursts of traffic, such as when users are interacting rapidly over chat. This limit prevents errors in sending logic from inadvertently draining the battery on a device.

For iOS, we return an error when the rate exceeds APNs limits.

FCM ports and your firewall

If your organization has a firewall to restrict traffic to or from the Internet, you need to configure it to allow mobile devices to connect with FCM in order for devices on your network to receive messages. FCM typically uses port 5228, but it sometimes uses 443, 5229, and 5230.

For devices connecting on your network, FCM doesn't provide specific IPs because our IP range changes too frequently and your firewall rules could get out of date, impacting your users' experience. Ideally, allowlist ports 5228-5230 & 443 with no IP restrictions. However, if you must have an IP restriction, you should allowlist all of the IP addresses listed in goog.json . This large list is updated regularly, and you are recommended to update your rules on a monthly basis. Problems caused by firewall IP restrictions are often intermittent and difficult to diagnose.

We do offer a set of domain names that can be allowlisted instead of IP addresses. Those hostnames are listed below. If we start using additional hostnames, we will update the list here. Using domain names for your firewall rule may or may not be functional in your firewall device.

TCP ports to open:

• 5228
• 5229
• 5230
• 443

Hostnames to open:

• mtalk.google.com
• mtalk4.google.com
• mtalk-staging.google.com
• mtalk-dev.google.com
• alt1-mtalk.google.com
• alt2-mtalk.google.com
• alt3-mtalk.google.com
• alt4-mtalk.google.com
• alt5-mtalk.google.com
• alt6-mtalk.google.com
• alt7-mtalk.google.com
• alt8-mtalk.google.com
• android.apis.google.com
• device-provisioning.googleapis.com
• firebaseinstallations.googleapis.com

Network Address Translation and/or Stateful Packet Inspection firewalls:

If your network implements Network Address Translation (NAT) or Stateful Packet Inspection (SPI), implement a 30 minute or larger timeout for our connections over ports 5228-5230. This enables us to provide reliable connectivity while reducing the battery consumption of your users' mobile devices.

VPN interactions and bypassability

Firebase Cloud Messaging takes various steps to ensure that the push messaging connection from the phone to the server is reliable and available as often as possible. The use of a VPN complicates this effort.

VPNs mask the underlying information that FCM needs to tune its connection to maximize reliability & battery life. In some cases VPNs actively break long lived connections resulting in a bad user experience due to missed or delayed messages or a high battery cost. When the VPN is configured to allow us to do so, we bypass the VPN using an encrypted connection (over the base network wifi or LTE) so as to ensure a reliable, battery friendly experience. FCM 's usage of bypassable VPNs is specific to the FCM Push Notification channel. Other FCM traffic, such as registration traffic, uses the VPN if it is active. When the FCM connection bypasses the VPN it loses additional benefits the VPN may provide, such as IP masking.

Different VPNs will have different methods for controlling whether or not it can be bypassed. Consult the documentation for your specific VPN for instructions.

If the VPN is not configured to be bypassable then Firebase Cloud Messaging will use the VPN network in order to connect to the server. This may result in periods of time where messages are delayed and may result in more battery usage as Cloud Messaging works to maintain the connection over the VPN connection.

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

Depending on which FCM features you implement, you may need the following credentials from your Firebase project:

Firebase Cloud Messaging ( FCM ) offers a broad range of messaging options and capabilities. The information in this page is intended to help you understand the different types of FCM messages and what you can do with them.

Message types

With FCM , you can send two types of messages to clients:

• Notification messages, sometimes thought of as "display messages." These are handled by the FCM SDK automatically.
• Data messages, which are handled by the client app.

Notification messages contain a predefined set of user-visible keys. Data messages, by contrast, contain only your user-defined custom key-value pairs. Notification messages can contain an optional data payload. Maximum payload for both message types is 4096 bytes, except when sending messages from the Firebase console, which enforces a 1000 character limit.

Use notification messages when you want the FCM SDK to handle displaying a notification automatically when your app is running in the background. Use data messages when you want to process the messages with your own client app code.

FCM can send a notification message including an optional data payload. In such cases, FCM handles displaying the notification payload, and the client app handles the data payload.

Notification messages

For testing or for marketing and user re-engagement, you can send notification messages using the Firebase console . The Firebase console provides analytics-based A/B testing to help you refine and improve marketing messages.

To programmatically send notification messages using the Admin SDK or the FCM protocols, set the notification key with the necessary predefined set of key-value options for the user-visible part of the notification message. For example, here is a JSON-formatted notification message in an IM app. The user can expect to see a message with the title "Portugal vs. Denmark" and the text "great match!" on the device:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    }
  }
}

Notification messages are delivered to the notification tray when the app is in the background. For apps in the foreground, messages are handled by a callback function.

See the HTTP v1 Protocol notification object reference documentation for the full list of predefined keys available for building notification messages.

Data messages

Set the appropriate key with your custom key-value pairs to send a data payload to the client app.

For example, here is a JSON-formatted message in the same IM app as above, where the information is encapsulated in the common data key and the client app is expected to interpret the content:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    }
  }
}

The above example shows usage of the top-level, or common data field, which is interpreted by clients on all platforms that receive the message. On each platform, the client app receives the data payload in a callback function.

Encryption for data messages

The Android Transport Layer (see FCM architecture ) uses point-to-point encryption. Depending on your needs, you may decide to add end-to-end encryption to data messages. FCM does not provide an end-to-end solution. However, there are external solutions available such as Capillary or DTLS .

Notification messages with optional data payload

Both programmatically or via the Firebase console, you can send notification messages that contain an optional payload of custom key-value pairs. In the Notifications composer , use the Custom data fields in Advanced options .

App behavior when receiving messages that include both notification and data payloads depends on whether the app is in the background or the foreground—essentially, whether or not it is active at the time of receipt.

• When in the background , apps receive the notification payload in the notification tray, and only handle the data payload when the user taps on the notification.
• When in the foreground , your app receives a message object with both payloads available.

Here is a JSON-formatted message containing both the notification key and the data key:

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

Customizing a message across platforms

The Firebase Admin SDK and the FCM v1 HTTP protocol both allow your message requests to set all fields available in the message object. Это включает в себя:

• a common set of fields to be interpreted by all app instances that receive the message.
• platform-specific sets of fields, such as AndroidConfig and WebpushConfig , interpreted only by app instances running on the specified platform.

Platform-specific blocks give you flexibility to customize messages for different platforms to ensure that they are handled correctly when received. The FCM backend will take all specified parameters into account and customize the message for each platform.

When to use common fields

Use common fields when you're:

• Targeting app instances on all platforms — Apple, Android, and web
• Sending messages to topics

All app instances, regardless of platform, can interpret the following common fields:

• message.notification.title
• message.notification.body
• message.data

When to use platform-specific fields

Use platform-specific fields when you want to:

• Send fields only to particular platforms
• Send platform-specific fields in addition to the common fields

Whenever you want to send values only to particular platforms, don't use common fields; use platform-specific fields. For example, to send a notification only to Apple platforms and web but not to Android, you must use two separate sets of fields, one for Apple and one for web.

When you are sending messages with specific delivery options , use platform-specific fields to set them. You can specify different values per platform if you want. However, even when you want to set essentially the same value across platforms, you must use platform-specific fields. This is because each platform may interpret the value slightly differently—for example, time-to-live is set on Android as an expiration time in seconds, while on Apple it is set as an expiration date .

Example: notification message with platform-specific delivery options

The following v1 send request sends a common notification title and content to all platforms, but also sends some platform-specific overrides. Specifically, the request:

• sets a long time-to-live for Android and Web platforms, while setting the APNs (Apple platforms) message priority to a low setting
• sets the appropriate keys to define the result of a user tap on the notification on Android and Apple — click_action , and category , respectively.

{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"Match update",
       "body":"Arsenal goal in added time, score is now 3-0"
     },
     "android":{
       "ttl":"86400s",
       "notification"{
         "click_action":"OPEN_ACTIVITY_1"
       }
     },
     "apns": {
       "headers": {
         "apns-priority": "5",
       },
       "payload": {
         "aps": {
           "category": "NEW_MESSAGE_CATEGORY"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

See the HTTP v1 reference documentation for complete detail on the keys available in platform-specific blocks in the message body. For more information about building send requests that contain the message body, see Build Send Requests .

Delivery options

FCM provides a specific set of delivery options for messages sent to Android devices, and allows for similar options on Apple platforms and web. For example, "collapsible" message behavior is supported on Android via FCM 's collapse_key , on Apple via apns-collapse-id , and on JavaScript/Web via Topic . For details, see descriptions in this section and related reference documentation.

Non-collapsible and collapsible messages

A non-collapsible message denotes that each individual message is delivered to the device. A non-collapsible message delivers some useful content, as opposed to a collapsible message like a content-free "ping" to the mobile app to contact the server to fetch data.

Some typical use cases of non-collapsible messages are chat messages or critical messages. For example, in an IM app, you would want to deliver every message, because every message has different content.

For Android there is a limit of 100 messages that can be stored without collapsing. If the limit is reached, all stored messages are discarded. When the device is back online, it receives a special message indicating that the limit was reached. The app can then handle the situation properly, typically by requesting a full sync from the app server.

A collapsible message is a message that may be replaced by a new message if it has yet to be delivered to the device.

A common use cases of collapsible messages are messages used to tell a mobile app to sync data from the server. An example would be a sports app that updates users with the latest score. Only the most recent message is relevant.

To mark a message as collapsible on Android, include the collapse_key parameter in the message payload. By default, the collapse key is the app package name registered in the Firebase console. The FCM server can simultaneously store four different collapsible messages per device, each with a different collapse key. If you exceed this number, FCM only keeps four collapse keys, with no guarantees about which ones are kept.

Topic messages with no payload are collapsible by default. Notification messages are always collapsible and will ignore the collapse_key parameter.

Which should I use?

Collapsible messages are a better choice from a performance standpoint, provided your app doesn't need to use non-collapsible messages. However, if you use collapsible messages, remember that FCM only allows a maximum of four different collapse keys to be used by FCM per registration token at any given time. You must not exceed this number, or it could cause unpredictable consequences.

Setting the priority of a message

You have two options for assigning delivery priority to downstream messages: normal and high priority. Though the behavior differs slightly across platforms, delivery of normal and high priority messages works like this:

• Normal priority. Normal priority messages are delivered immediately when the app is in the foreground. For backgrounded apps, delivery may be delayed. For less time-sensitive messages, such as notifications of new email, keeping your UI in sync, or syncing app data in the background, choose normal delivery priority.

• High priority. FCM attempts to deliver high priority messages immediately even if the device is in Doze mode. High priority messages are for time-sensitive, user visible content.

Here is an example of a normal priority message sent via the FCM HTTP v1 protocol to notify a magazine subscriber that new content is available to download:

{
  "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"
      }
    }
  }
}

For more platform-specific detail on setting message priority:

• APNs documentation
• Set and manage message priority (Android)
• Web push message urgency

Life critical use cases

The FCM APIs are not designed for emergency alerts or other high-risk activities where the use or failure of the APIs could result in death, personal injury, or environmental damage (such as the operation of nuclear facilities, air traffic control, or life support systems). Any such use is expressly prohibited under Section 4. a. 7 of the Terms of Service. You are solely responsible for managing your app's compliance with the Terms, and any damages resulting from your noncompliance. Google provides the APIs "as is," and reserves the right to discontinue the APIs or any portion or feature or your access thereto, for any reason and at any time, without liability or other obligation to you or your users.

Setting the lifespan of a message

FCM usually delivers messages immediately after they are sent. However, this might not always be possible. For example, if the platform is Android, the device could be turned off, offline, or otherwise unavailable. Or FCM might intentionally delay messages to prevent an app from consuming excessive resources and negatively affecting battery life.

When this happens, FCM stores the message and delivers it as soon as it's feasible. While this is fine in most cases, there are some apps for which a late message might as well never be delivered. For example, if the message is an incoming call or video chat notification, it is meaningful only for a short period of time before the call is terminated. Or if the message is an invitation to an event, it is useless if received after the event has ended.

On Android and Web/JavaScript, you can specify the maximum lifespan of a message. The value must be a duration from 0 to 2,419,200 seconds (28 days), and it corresponds to the maximum period of time for which FCM stores and attempts to deliver the message. Requests that don't contain this field default to the maximum period of four weeks.

Here are some possible uses for this feature:

• Video chat incoming calls
• Expiring invitation events
• Calendar events

Another advantage of specifying the lifespan of a message is that FCM doesn't apply collapsible message throttling to messages with a time-to-live value of 0 seconds. FCM provides best effort handling of messages that must be delivered "now or never." Keep in mind that a time_to_live value of 0 means messages that can't be delivered immediately are discarded. However, because such messages are never stored, this provides the best latency for sending notification messages.

Here is an example of a request that includes 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"
      }
    }
  }
}

Lifetime of a message

When an app server posts a message to FCM and receives a message ID back, it does not mean that the message was already delivered to the device. Rather, it means that it was accepted for delivery. What happens to the message after it is accepted depends on many factors.

In the best-case scenario, if the device is connected to FCM , the screen is on and there are no throttling restrictions, the message is delivered right away.

If the device is connected but in Doze, a low priority message is stored by FCM until the device is out of Doze. And that's where the collapse_key flag plays a role: if there is already a message with the same collapse key (and registration token) stored and waiting for delivery, the old message is discarded and the new message takes its place (that is, the old message is collapsed by the new one). However, if the collapse key is not set, both the new and old messages are stored for future delivery.

If the device is not connected to FCM , the message is stored until a connection is established (again respecting the collapse key rules). When a connection is established, FCM delivers all pending messages to the device. If the device never gets connected again (for instance, if it was factory reset), the message eventually times out and is discarded from FCM storage. The default timeout is four weeks, unless the time_to_live flag is set.

To get more insight into the delivery of a message:

To get more insight into the delivery of messages on Android or Apple platforms, see the FCM reporting dashboard , which records the number of messages sent and opened on Apple and Android devices, along with data for "impressions" (notifications seen by users) for Android apps.

For Android devices with direct channel messaging enabled, if the device has not connected to FCM for more than one month, FCM still accepts the message but immediately discards it. If the device connects within four weeks of the last data message you sent to it, your client receives the onDeletedMessages() callback. The app can then handle the situation properly, typically by requesting a full sync from the app server.

Finally, when FCM attempts to deliver a message to the device and the app was uninstalled, FCM discards that message right away and invalidates the registration token. Future attempts to send a message to that device results in a NotRegistered error.

Throttling and quotas

Our goal is to always deliver every message sent via FCM. However, delivering every message sometimes results in a poor overall user experience. In other cases, we need to provide boundaries to ensure that FCM provides a scalable service for all senders. The types of limits and quotas described in this section help us balance these important factors.

Downstream message throttling

The HTTP v1 API introduced per-project, per-minute quotas for downstream messaging. The default quota of 600k messages per minute covers over 99% of FCM developers while protecting the stability of the system and minimizing the impact of spiky projects.

Spiky traffic patterns can result in quota exceeded errors. In an over quota scenario, the system serves HTTP status code 429 (QUOTA_EXCEEDED) until the quota is refilled in the following minute. 429 responses may also be returned in overload situations, so you are strongly encouraged to handle 429s according to published recommendations .

Обратите внимание, что:

• The downstream quota measures messages, not requests.
• Client errors (HTTP status code 400-499) are counted (excluding 429s).
• Quotas are per-minute, but these minutes are not aligned to the clock.

Monitoring quota

You can view quota, usage, and errors on the Google Cloud Console:

1. Go to the Google Cloud console
2. Select APIs & services
3. From the table list, select Firebase Cloud Messaging API
4. Select QUOTA & SYSTEM LIMITS .

NOTE: These graphs are not precisely time aligned with quota minutes, meaning 429s may be served when traffic appears to be below quota.

Requesting a quota increase

Before requesting a quota increase, ensure that:

• Your usage is regularly ≥ 80% of quota for at least 5 consecutive minutes per day.
• You have < 5% client error ratio, especially during peak traffic.
• You adhere to the best practices for sending messages at scale .

If you meet these criteria, you can submit a quota increase request for up to +25% and FCM will make every practical effort to fulfill the request (no increase can be guaranteed).

If you need more downstream messaging quota due to an impending launch or temporary event, request your quota at least 15 days in advance to allow sufficient time to handle the request. For large requests (>18M messages per minute), at least 30 days of notice is required. Launches and special event requests are still subject to the client error ratio and best practices requirements.

See also the FAQ about FCM quotas .

Topic message limit

The topic subscription add/remove rate is limited to 3,000 QPS per project.

For message sending rates, see Fanout Throttling .

Fanout throttling

Message fanout is the process of sending a message to multiple devices, such as when you target topics and groups, or when you use the Notifications composer to target audiences or user segments.

Message fanout is not instantaneous and so occasionally you have multiple fanouts in progress concurrently. We limit the number of concurrent message fanouts per project to 1,000. After that, we may reject additional fanout requests or defer the fanout of the requests until some of the already in progress fanouts complete.

The actual achievable fanout rate is influenced by the number of projects requesting fanouts at the same time. A fanout rate of 10,000 QPS for an individual project is not uncommon, but that number is not a guarantee and is a result of the total load on the system. It is important to note that the available fanout capacity is divided among projects and not across fanout requests. So, if your project has two fanouts in progress, then each fanout will only see half of the available fanout rate. The recommended way to maximize your fanout speed is to only have one active fanout in progress at a time.

Collapsible message throttling

As described above, collapsible messages are content-free notifications designed to collapse on top of each other. In the event that a developer is repeating the same message to an app too frequently, we delay (throttle) messages to reduce the impact on a user's battery.

For example, if you send large numbers of new email sync requests to a single device, we might delay the next email sync request a few minutes so that the device can sync at a lower average rate. This throttling is done strictly to limit the battery impact experienced by the user.

If your use case requires high burst send patterns, then non-collapsible messages may be the right choice. For such messages, make sure to include the content in such messages in order to reduce the battery cost.

We limit collapsible messages to a burst of 20 messages per app per device, with a refill of 1 message every 3 minutes.

Maximum message rate to a single device

For Android, you can send up to 240 messages/minute and 5,000 messages/hour to a single device. This high threshold is meant to allow for short term bursts of traffic, such as when users are interacting rapidly over chat. This limit prevents errors in sending logic from inadvertently draining the battery on a device.

For iOS, we return an error when the rate exceeds APNs limits.

FCM ports and your firewall

If your organization has a firewall to restrict traffic to or from the Internet, you need to configure it to allow mobile devices to connect with FCM in order for devices on your network to receive messages. FCM typically uses port 5228, but it sometimes uses 443, 5229, and 5230.

For devices connecting on your network, FCM doesn't provide specific IPs because our IP range changes too frequently and your firewall rules could get out of date, impacting your users' experience. Ideally, allowlist ports 5228-5230 & 443 with no IP restrictions. However, if you must have an IP restriction, you should allowlist all of the IP addresses listed in goog.json . This large list is updated regularly, and you are recommended to update your rules on a monthly basis. Problems caused by firewall IP restrictions are often intermittent and difficult to diagnose.

We do offer a set of domain names that can be allowlisted instead of IP addresses. Those hostnames are listed below. If we start using additional hostnames, we will update the list here. Using domain names for your firewall rule may or may not be functional in your firewall device.

TCP ports to open:

• 5228
• 5229
• 5230
• 443

Hostnames to open:

• mtalk.google.com
• mtalk4.google.com
• mtalk-staging.google.com
• mtalk-dev.google.com
• alt1-mtalk.google.com
• alt2-mtalk.google.com
• alt3-mtalk.google.com
• alt4-mtalk.google.com
• alt5-mtalk.google.com
• alt6-mtalk.google.com
• alt7-mtalk.google.com
• alt8-mtalk.google.com
• android.apis.google.com
• device-provisioning.googleapis.com
• firebaseinstallations.googleapis.com

Network Address Translation and/or Stateful Packet Inspection firewalls:

If your network implements Network Address Translation (NAT) or Stateful Packet Inspection (SPI), implement a 30 minute or larger timeout for our connections over ports 5228-5230. This enables us to provide reliable connectivity while reducing the battery consumption of your users' mobile devices.

VPN interactions and bypassability

Firebase Cloud Messaging takes various steps to ensure that the push messaging connection from the phone to the server is reliable and available as often as possible. The use of a VPN complicates this effort.

VPNs mask the underlying information that FCM needs to tune its connection to maximize reliability & battery life. In some cases VPNs actively break long lived connections resulting in a bad user experience due to missed or delayed messages or a high battery cost. When the VPN is configured to allow us to do so, we bypass the VPN using an encrypted connection (over the base network wifi or LTE) so as to ensure a reliable, battery friendly experience. FCM 's usage of bypassable VPNs is specific to the FCM Push Notification channel. Other FCM traffic, such as registration traffic, uses the VPN if it is active. When the FCM connection bypasses the VPN it loses additional benefits the VPN may provide, such as IP masking.

Different VPNs will have different methods for controlling whether or not it can be bypassed. Consult the documentation for your specific VPN for instructions.

If the VPN is not configured to be bypassable then Firebase Cloud Messaging will use the VPN network in order to connect to the server. This may result in periods of time where messages are delayed and may result in more battery usage as Cloud Messaging works to maintain the connection over the VPN connection.

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

Depending on which FCM features you implement, you may need the following credentials from your Firebase project: