Google стремится продвигать расовую справедливость для черных сообществ. Смотри как.
Эта страница была переведа с помощью Cloud Translation API.
Switch to English

Ваша серверная среда и FCM

Серверная часть Firebase Cloud Messaging состоит из двух компонентов:

  • Серверная часть FCM предоставлена ​​Google.
  • Сервер приложений или другая доверенная серверная среда, в которой работает логика вашего сервера, например облачные функции для Firebase или другие облачные среды, управляемые Google.

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

Требования к среде доверенного сервера

Ваша среда сервера приложений должна соответствовать следующим критериям:

  • Возможность отправлять правильно отформатированные запросы сообщений в серверную часть FCM.
  • Умеет обрабатывать запросы и отправлять их, используя экспоненциальный откат.
  • Возможность безопасного хранения учетных данных авторизации сервера и токенов регистрации клиента.
  • Для протокола XMPP (если используется) сервер должен иметь возможность генерировать идентификаторы сообщений для уникальной идентификации каждого отправляемого сообщения (HTTP-сервер FCM создает идентификаторы сообщений и возвращает их в ответе). Идентификаторы сообщений XMPP должны быть уникальными для каждого идентификатора отправителя.

Выбор варианта сервера

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

Варианты взаимодействия с серверами FCM включают следующее:
  • Firebase Admin SDK, который поддерживает Node , Java , Python , C # и Go .
  • API FCM HTTP v1 , который является самой современной из опций протокола, с более безопасной авторизацией и гибкими возможностями межплатформенного обмена сообщениями (Firebase Admin SDK основан на этом протоколе и обеспечивает все его присущие преимущества).
  • Устаревший протокол HTTP .
  • Протокол XMPP- сервера. Обратите внимание, что если вы хотите использовать восходящий обмен сообщениями из ваших клиентских приложений, вы должны использовать XMPP.

Firebase Admin SDK для FCM

Admin FCM API выполняет аутентификацию с помощью бэкэнда и облегчает отправку сообщений и управление подписками на темы. С помощью Firebase Admin SDK вы можете:

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

Admin Node.js SDK предоставляет методы для отправки сообщений в группы устройств.

Чтобы настроить Firebase Admin SDK, см. Раздел «Добавление Firebase Admin SDK на ваш сервер» . Если у вас уже есть проект Firebase, начните с добавления SDK . Затем, после установки Firebase Admin SDK, вы можете начать писать логику для создания запросов на отправку .

Протоколы сервера FCM

В настоящее время FCM предоставляет следующие необработанные серверные протоколы:

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

Обмен сообщениями XMPP отличается от обмена сообщениями HTTP следующими способами:

  • Upstream / Downstream сообщения
    • HTTP: только в нисходящем направлении, облако на устройство.
    • XMPP: восходящий и нисходящий (от устройства к облаку, от облака к устройству).
  • Обмен сообщениями (синхронный или асинхронный)
    • HTTP: синхронный. Серверы приложений отправляют сообщения в виде запросов HTTP POST и ожидают ответа. Этот механизм является синхронным и блокирует отправителя отправлять другое сообщение до получения ответа.
    • XMPP: асинхронный. Серверы приложений отправляют / получают сообщения со всех своих устройств со всех своих устройств на постоянной скорости по постоянным соединениям XMPP. Сервер соединений XMPP отправляет уведомления о подтверждении или сбое (в форме специальных сообщений XMPP в кодировке ACK и NACK JSON) асинхронно.
  • JSON
    • HTTP: сообщения JSON, отправленные как HTTP POST.
    • XMPP: сообщения JSON, инкапсулированные в сообщения XMPP.
  • Простой текст
    • HTTP: обычные текстовые сообщения, отправленные как HTTP POST.
    • XMPP: не поддерживается.
  • Многоадресная рассылка отправляется на несколько регистрационных токенов.
    • HTTP: поддерживается в формате сообщения JSON.
    • XMPP: не поддерживается.

Реализация протокола HTTP-сервера

Чтобы отправить сообщение, сервер приложений выдает запрос POST с заголовком HTTP и телом HTTP, состоящим из пар ключ-значение JSON. Подробнее о параметрах заголовка и тела см. В разделе Создание запросов на отправку сервера приложений.

Реализация протокола сервера XMPP

Полезная нагрузка JSON для сообщений FCM аналогична протоколу HTTP, за следующими исключениями:

  • Нет поддержки для нескольких получателей.
  • FCM добавляет поле message_id , которое является обязательным. Этот идентификатор уникально идентифицирует сообщение в соединении XMPP. ACK или NACK от FCM использует message_id для идентификации сообщения, отправленного с серверов приложений на FCM. Поэтому важно, чтобы этот message_id не только был уникальным (для каждого отправителя ), но и всегда присутствовал.
  • XMPP использует ключ сервера для авторизации постоянного соединения с FCM. См. Авторизация Отправить запросы для получения дополнительной информации.

В дополнение к обычным сообщениям FCM отправляются управляющие сообщения, указанные полем message_type в объекте JSON. Значением может быть «ack», «nack» или «control» (см. Форматы ниже). Любое сообщение FCM с неизвестным message_type может быть проигнорировано вашим сервером.

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

FCM также отправляет ACK или NACK для каждого сообщения сервер-устройство. Если вы ничего не получили, это означает, что TCP-соединение было закрыто в середине операции, и ваш сервер должен повторно отправить сообщения. См. Контроль потока для деталей.

См. Ссылку на протокол для получения списка всех параметров сообщения.

Формат запроса

Сообщение с полезной нагрузкой - уведомление

Вот раздел XMPP для уведомления:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
     "notification": {
        "title": "Portugal vs. Denmark”,
        "body”: "5 to 1”
      },
      "time_to_live":"600"
}

  }
  </gcm>
</message>

Сообщение с полезной нагрузкой - сообщение с данными

Вот раздел XMPP, содержащий сообщение JSON с сервера приложений в FCM:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
      "message_id":"m-1366082849205" // new required field
      "data":
      {
          "hello":"world",
      }
      "time_to_live":"600",
  }
  </gcm>
</message>

Формат ответа

Ответ FCM может иметь три возможных формы. Первое - обычное сообщение «ack». Но когда в ответе содержится ошибка, сообщение может принимать 2 различные формы, описанные ниже.

ACK сообщение

Вот раздел XMPP, содержащий сообщение ACK / NACK от FCM на сервер приложений:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

NACK сообщение

Ошибка NACK - это обычное сообщение XMPP, в котором сообщением о статусе message_type является «nack». NACK-сообщение содержит:

  • Код ошибки NACK.
  • Описание ошибки NACK.

Ниже приведены некоторые примеры.

Плохая регистрация:

<message>
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"SomeInvalidRegistrationId",
    "error":"BAD_REGISTRATION",
    "error_description":"Invalid token on 'to' field: SomeInvalidRegistrationId"
  }
  </gcm>
</message>

Неверный JSON:

<message>
 <gcm xmlns="google:mobile:data">
 {
   "message_type":"nack",
   "message_id":"msgId1",
   "from":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
   "error":"INVALID_JSON",
   "error_description":"InvalidJson: JSON_TYPE_ERROR : Field \"time_to_live\" must be a JSON java.lang.Number: abc"
 }
 </gcm>
</message>

Превышена частота сообщений устройства:

<message id="...">
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"REGID",
    "error":"DEVICE_MESSAGE_RATE_EXCEEDED",
    "error_description":"Downstream message rate exceeded for this registration id"
  }
  </gcm>
</message>

См. Ссылку на сервер для получения полного списка кодов ошибок NACK. Если не указано иное, сообщение NACKed не следует повторять. Неожиданные коды ошибок NACK должны обрабатываться так же, как и INTERNAL_SERVER_ERROR .

Ошибка строфы

Вы также можете получить ошибку в некоторых случаях. Ошибка строфа содержит:

  • Код ошибки Stanza.
  • Описание ошибки Stanza (свободный текст).

Например:

<message id="3" type="error" to="123456789@fcm.googleapis.com/ABC">
  <gcm xmlns="google:mobile:data">
     {"random": "text"}
  </gcm>
  <error code="400" type="modify">
    <bad-request xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
    <text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">
      InvalidJson: JSON_PARSING_ERROR : Missing Required Field: message_id\n
    </text>
  </error>
</message>

Контрольные сообщения

Периодически FCM необходимо закрывать соединение для балансировки нагрузки. Перед тем как закрыть соединение, FCM отправляет сообщение CONNECTION_DRAINING чтобы указать, что соединение очищается и скоро будет закрыто. «Слив» означает отключение потока сообщений, поступающих в соединение, но разрешение на продолжение всего, что уже находится в конвейере. Получив сообщение CONNECTION_DRAINING , вы должны немедленно начать отправку сообщений на другое соединение FCM, открывая новое соединение, если это необходимо. Однако вы должны держать исходное соединение открытым и продолжать получать сообщения, которые могут прийти по соединению (и ACKing их) - FCM обрабатывает инициацию соединения, когда оно готово.

Сообщение CONNECTION_DRAINING выглядит так:

<message>
  <data:gcm xmlns:data="google:mobile:data">
  {
    "message_type":"control"
    "control_type":"CONNECTION_DRAINING"
  }
  </data:gcm>
</message>

CONNECTION_DRAINING в настоящее время является единственным поддерживаемым control_type .

Управление потоком

Каждое сообщение, отправленное в FCM, получает ответ ACK или NACK. Сообщения, которые не получили ни одного из этих ответов, считаются ожидающими. Если число ожидающих сообщений достигает 100, сервер приложений должен прекратить отправку новых сообщений и ждать, пока FCM подтвердит некоторые из существующих ожидающих сообщений, как показано на рисунке 1:

Рисунок 1. Поток сообщений / подтверждений.

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

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