1. Введение
Цели
В этом практическом занятии вы узнаете, как модифицировать ваше многоплатформенное приложение, чтобы отправлять push-уведомления различным подгруппам экземпляров вашего приложения с помощью тем FCM.
После завершения вы сможете использовать инфраструктуру FCM для управления этими подгруппами, а также для отправки многоадресных push-сообщений через эти подгруппы.
Обзор тем
Темы — это поддерживаемый инфраструктурой FCM способ отправки сообщений подгруппам экземпляров вашего приложения.
FCM предоставляет API для отправки сообщений, а также для управления подписками на эти темы. Процессы связывания и отсоединения экземпляра приложения от темы называются соответственно подпиской и отменой подписки.
Темы следует использовать для общедоступного контента. Например, сообщения об обновлениях погоды. Если вы хотите отправлять сообщения, содержащие конфиденциальную информацию о пользователе, используйте Firebase Admin SDK для многоадресной рассылки сообщений на несколько устройств .
Многоадресная рассылка по темам оптимизирована для повышения пропускной способности.
Что вы узнаете
- Как подписывать (и отписывать) пользователей от тем из мобильного приложения.
- Как отправлять многоадресные push-сообщения с использованием тем.
- Как отправлять сообщения в комбинацию тем с использованием условий для тем.
- Как управлять подписками на темы на стороне сервера и выполнять массовые подписки и отписки.
Что вы построите
- Приложение для Android, которое позволяет подписываться/отписываться от тем и получать сообщения, отправленные в эти темы.
- Интеграция на стороне сервера с использованием Firebase Admin SDK, которая будет применяться для отправки сообщений в темы через API FCM.
Что вам понадобится
- Любой браузер на ваш выбор, например Chrome.
- IntelliJ IDEA — среда разработки для создания Java-приложений.
- Обязательно включите поддержку Gradle во время установки.
- Android Studio — интегрированная среда разработки для создания приложений под Android.
- Устройство для запуска Android-приложения. Одно из следующих:
- Эмулятор Android. (Требуется настройка в Android Studio ).
- Физическое устройство Android, подключенное к компьютеру и настроенное на режим разработчика.
- Учетная запись Google для создания и управления вашим проектом Firebase.
2. Настройка
Получите код
Клонируйте репозиторий GitHub из командной строки:
git clone https://github.com/firebase/quickstart-android.git fcm-codelab
Пример кода будет клонирован в каталог fcm-codelab .
cd fcm-codelab
Стартовое приложение для этого практического занятия находится в каталоге messaging ветки fcm-topics-codelab . Чтобы получить доступ к стартовому коду, выполните следующие шаги. Оно содержит два каталога: StockNewsApp и StockNewsServer . В первом находится стартовое приложение для Android, а во втором — стартовый серверный код.
git checkout fcm-topics-codelab cd messaging/fcm-topics-codelab/starter
Завершенная версия этого практического занятия находится в каталоге messaging/fcm-topics-codelab/completed .
Создайте проект Firebase.
- Войдите в консоль Firebase, используя свою учетную запись Google.
- Нажмите кнопку, чтобы создать новый проект, а затем введите название проекта (например,
StockNews). - Нажмите «Продолжить» .
- Если появится запрос, ознакомьтесь с условиями использования Firebase и примите их, после чего нажмите «Продолжить» .
- (Необязательно) Включите помощь ИИ в консоли Firebase (в Firebase она называется "Gemini").
- Для этого практического занятия вам не понадобится Google Analytics, поэтому отключите эту опцию.
- Нажмите «Создать проект» , дождитесь завершения подготовки проекта, а затем нажмите «Продолжить» .
Поздравляем! Вы только что создали свой проект Firebase.
3. Конфигурация приложения Firebase для конкретной платформы
Большинство изменений в коде, необходимых для включения поддержки Firebase, уже внесены в проект, над которым вы работаете. Однако для добавления поддержки мобильных платформ вам необходимо:
- Зарегистрируйте нужную платформу в проекте Firebase.
- Загрузите конфигурационный файл, специфичный для вашей платформы, и добавьте его в код.
В рамках этого практического занятия мы добавим Android-приложение Firebase.
Настройка Android
- В консоли Firebase выберите «Настройки проекта» в верхней части левой панели навигации в меню «Настройки» и нажмите значок Android в разделе «Ваши приложения» на странице «Общие» .
Вы должны увидеть следующее диалоговое окно: 
- Важно указать имя пакета Android . Установите его значение равным
com.ticker.stocknews.- Указанное здесь имя пакета должно совпадать с именем пакета, указанным в файле
AndroidManifest.xmlвашего стартового кода StockNewsApp . Если вы хотите найти или изменить его, выполните следующие шаги:- В каталоге StockNewsApp откройте файл
app/src/main/AndroidManifest.xml. - В элементе
manifestнайдите строковое значение атрибутаpackage. Это значение представляет собой имя пакета Android.
- В каталоге StockNewsApp откройте файл
- Указанное здесь имя пакета должно совпадать с именем пакета, указанным в файле
- В диалоговом окне Firebase вставьте скопированное имя пакета в поле "Имя пакета Android" .
- Для этого практического задания вам не понадобится сертификат подписи отладчика SHA-1 , поскольку это приложение не будет выпущено. Оставьте это поле пустым.
- Нажмите «Зарегистрировать приложение» .
- Продолжая работу в консоли Firebase, следуйте инструкциям, чтобы загрузить файл конфигурации
google-services.json. - Оставшиеся шаги настройки можно пропустить, так как все остальное уже сконфигурировано в коде стартового приложения. Ваше приложение будет отображаться на главной странице консоли Firebase.
- Скопируйте файл
google-services.json(который вы только что скачали) в каталогmessaging/fcm-topics-codelab/starter/StockNewsApp/app.
4. Создайте и запустите свое приложение.
Вы готовы приступить к работе над своим приложением! Для начала соберите и запустите приложение.
Импортируйте стартовое приложение
Запустите Android Studio и импортируйте приложение messaging/fcm-topics-codelab/starter/StockNewsApp из каталога с исходным кодом.
После загрузки проекта вы также можете увидеть предупреждение о том, что Git не отслеживает все ваши локальные изменения. В этом случае вы можете нажать « Игнорировать » или крестик в правом верхнем углу. (Вы не будете отправлять изменения обратно в репозиторий Git.)
В верхнем левом углу окна проекта, если вы находитесь в режиме просмотра Android , вы должны увидеть что-то похожее на изображение ниже. (Если вы находитесь в режиме просмотра проекта , вам нужно будет развернуть проект, чтобы увидеть то же самое).

Обратите внимание, что для первой компиляции проекта в фоновом режиме в Android Studio может потребоваться несколько секунд. В это время в строке состояния внизу окна Android Studio будет отображаться индикатор загрузки:

Мы рекомендуем дождаться завершения этого процесса, прежде чем вносить изменения в код. Это позволит Android Studio подключить все необходимые компоненты.
Кроме того, если появится сообщение типа «Перезагрузите страницу, чтобы изменения языка вступили в силу?» или что-то подобное, выберите «Да».
Настройка эмулятора
Если вам нужна помощь в настройке эмулятора Android, обратитесь к статье «Запуск приложения» .
Разберитесь в стартовом коде Android-приложения.
- Исходный код представляет собой легковесное Android-приложение с минимальным функционалом и пользовательским интерфейсом.
- Зависимость от firebase-messaging SDK уже добавлена в файл
app/build.gradle.

- В файле
AndroidManifest.xmlуже добавлен обработчик обратного вызоваMESSAGING_EVENT.- Этот обработчик,
StockNewsMessagingService.java, расширяет классFirebaseMessagingService, который предоставляет различные функции, связанные с Firebase Cloud Messaging. Для получения дополнительной информации см. документацию FirebaseMessagingService .

- Функция
onNewTokenвызывается при создании или обновлении регистрационного токена FCM. Дополнительную информацию см. в разделе «Мониторинг генерации токенов» . - Функция
onMessageReceivedвызывается при получении сообщения, когда приложение находится на переднем плане. В настоящее время она просто выводит полученное сообщение в лог.- Подробнее о различиях между фоновой и активной доставкой и обработкой сообщений см. в разделе «Получение сообщений в приложении Android» .
- Этот обработчик,
- Кроме того, в
AndroidManifest.xmlтакже указан класс AndroidApplicationс именемStockNewsApplication.

- Этот класс будет создан первым при запуске приложения.
- В функции
onCreateклассаStockNewsApplicationдобавлен вызов для создания регистрационного токена FCM. Он сгенерирует действительный регистрационный токен FCM и запишет его в лог.
- В файле
MainActivity.javaдобавляетсяRecyclerView, отображающий варианты категорий товаров. - В
SubscriptionAdapter.javaреализован интерфейсRecyclerView.Adapter, который отображает экран выбора категории товара.- Каждая категория акций имеет название и переключатель подписки рядом с ним.
- Изменение положения переключателя должно привести к вызову функции подписки/отписки от темы FCM.
- Вы реализуете эти вызовы в следующих разделах.
- Класс
model/StockCategories.javaсодержит список всех категорий акций и соответствующих им названий тем.

Запустите стартовое приложение
- Подключите ваше Android-устройство к компьютеру или запустите эмулятор.
- На верхней панели инструментов выберите целевое устройство Android или эмулятор и нажмите кнопку «Запустить».

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

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

5. Отправьте тестовое сообщение
Теперь вы готовы отправить тестовое сообщение в экземпляр приложения, который вы настроили на предыдущем шаге.
Импортируйте код стартового сервера.
Запустите IntelliJ IDEA и откройте проект messaging/fcm-topics-codelab/starter/StockNewsServer .
В левой панели навигации окно с описанием проекта должно выглядеть примерно так:

Обратите внимание, что сборка вашего проекта в IntelliJ IDEA, включая подключение необходимых зависимостей, может занять несколько минут.
Разберитесь с кодом запуска сервера.
- Запуск сервера осуществляется с помощью Java-проекта, созданного на основе Gradle.
- В файле
build.gradleуже добавлена зависимость от SDK firebase-admin . Этот SDK предоставляет доступ к различным функциям отправки сообщений FCM.

- Наконец, существуют два класса, а именно:
-
FcmSender.java: Этот класс содержит следующие важные методы:-
initFirebaseSDK: Инициализирует SDK firebase-admin. -
sendMessageToFcmRegistrationToken: отправить сообщение на токен регистрации FCM. -
sendMessageToFcmTopic: отправить сообщение в тему FCM. -
sendMessageToFcmTopicCondition: отправить сообщение в условие темы FCM.
-
-
FcmSubscriptionManager.java: Этот класс содержит методы, позволяющие управлять подписками на темы на стороне сервера.-
initFirebaseSDK: Инициализирует SDK firebase-admin. -
subscribeFcmRegistrationTokensToTopic: Подписывает(ют) регистрационные токены FCM на тему FCM. -
unsubscribeFcmRegistrationTokensFromTopic: отписка от токенов регистрации FCM из темы FCM.
-
-
Настройка серверного кода
- Во-первых, нам нужно настроить учетную запись службы Firebase, которая позволит SDK firebase-admin авторизовывать вызовы к API FCM.
- Перейдите в консоль Firebase, нажмите на значок шестеренки рядом с пунктом «Обзор проекта» в левой панели навигации и выберите «Настройки проекта» .

- На странице настроек выберите «Учетные записи служб» и нажмите «Создать учетную запись службы» .

- Теперь нажмите кнопку «Сгенерировать новый закрытый ключ» , и начнется автоматическая загрузка файла с вашим ключом.
- Переименуйте файл ключа в
service-account.jsonи скопируйте его в папкуmessaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources. - В файлах
FcmSender.javaиFcmSubscriptionManager.javaфайлservice-account.jsonзагружается из classpath с помощью следующего кода.
- Перейдите в консоль Firebase, нажмите на значок шестеренки рядом с пунктом «Обзор проекта» в левой панели навигации и выберите «Настройки проекта» .
- На этом этапе серверный код готов. Запустите команду Build -> Build Project из верхней панели меню.
Отправка тестового сообщения
- В
FcmSender.javaнайдите функциюsendMessageToFcmRegistrationTokenи вставьте скопированный из раздела «Запуск стартового приложения» токен регистрации FCM в полеregistrationToken. - В
mainфункции раскомментируйте только функциюsendMessageToFcmRegistrationTokenи нажмите кнопку "Выполнить", чтобы запустить код.- Обратите внимание, как регистрационный токен FCM устанавливается в поле
Tokenобъектаmessage. - Кроме того, обратите внимание, как мы использовали API
sendиз интерфейсаFirebaseMessaging.
- Обратите внимание, как регистрационный токен FCM устанавливается в поле

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

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

Отлично, вы использовали Firebase Admin SDK для отправки сообщений экземпляру приложения. Подробнее об использовании Firebase Admin SDK на вашем сервере можно прочитать здесь.
6. Реализация подписки/отписки на темы.
На этом этапе вы реализуете функции подписки и отписки от тем в переключателе категорий товаров в приложении для Android.
Когда пользователь приложения переключает тумблер для определенной категории акций, выполняется запрос на подписку или отмену подписки на тему.
Проверьте код
- Перейдите в файл
SubscriptionAdapter.javaв коде Android-приложения и найдите классRecyclerViewViewHolder.

- Конструктор класса настраивает слушатель для переключения подписки, используя
setOnCheckedChangeListener. - В зависимости от положения переключателя, действия подписки и отписки выполняются путем вызова методов
subscribeToStockCategoryиunsubscribeFromStockCategoryсоответственно. - Метод
setDataвызывается вonBindViewHolderадаптера RecyclerView для привязки ViewHolder к соответствующей категории товаров на складе.
Реализовать подписку на темы.
- В методе
subscribeToStockCategoryвам нужно будет реализовать вызов APIsubscribeToTopicобъектаFirebaseMessaging. Код может выглядеть примерно так:
void subscribeToStockCategory() {
// Making call to FCM for subscribing to the topic for stockCategory
FirebaseMessaging.getInstance().subscribeToTopic(stockCategory.getTopicName()).addOnSuccessListener(
unused -> {
// Subscribing action successful
Log.i(TAG, "Subscribed to topic: " + stockCategory.getTopicName());
Toast.makeText(itemView.getContext(), "Subscribed to " + stockCategory.getCategoryName(),
Toast.LENGTH_SHORT).show();
});
}
Реализовать отписку от темы.
- Аналогично, в условии else вам нужно будет выполнить вызов API
unsubscribeFromTopic. Примерно так:
void unsubscribeFromStockCategory() {
// Making call to FCM for unsubscribing from the topic for stockCategory
FirebaseMessaging.getInstance().unsubscribeFromTopic(stockCategory.getTopicName())
.addOnSuccessListener(unused -> {
// Unsubscribing action successful
Log.i(TAG, "Unsubscribed from topic: " + stockCategory.getTopicName());
Toast.makeText(itemView.getContext(), "Unsubscribed from " + stockCategory.getCategoryName(),
Toast.LENGTH_SHORT).show();
});
}
Давайте попробуем
- Запустите приложение и переключите параметры категорий акций, чтобы выполнить действия подписки и отписки. Это будет выглядеть примерно так:
Подписаться | Отписаться |
|
|
7. Отправка первого сообщения в теме письма.
На этом этапе вы реализуете серверный код для отправки сообщения из топика FCM.
Реализовать интеграцию на стороне сервера для отправки сообщений в заданную тему.
- В коде сервера перейдите в файл
FcmSender.javaи найдите методsendMessageToFcmTopic.

- В первой строке укажите тему FCM, в которую вы хотите отправить сообщение.
- Это строка вида:
/topics/<Topic Name>. Например,/topics/Technology.
- Это строка вида:
- В следующих строках создайте новый объект
message(аналогичный тому, который определен в функцииsendMessageToFcmRegistrationToken).- Разница будет заключаться в том, что вместо установки поля
Tokenв объектеmessageвы будете устанавливать полеTopic.
- Разница будет заключаться в том, что вместо установки поля
Message message = Message.builder()
.putData("FOOTECH", "$1000")
.setNotification(
Notification.builder()
.setTitle("Investor confidence in Tech Stocks growing")
.setBody("Foo Tech leading the way in stock growth for Tech sector.")
.build())
.setTopic(topicName)
.build();
- Теперь добавьте вызов к экземпляру
FirebaseMessagingдля отправки сообщения (идентичный вызову send, выполненному в функцииsendMessageToFcmRegistrationToken).
FirebaseMessaging.getInstance().send(message);
- Наконец, обновите
mainфункцию и включите возможность вызова только функцииsendMessageToFcmTopic.

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

- Теперь вы можете отправить сообщение с вашей темой, выполнив
mainфункцию файлаFcmSender.java. - Как и прежде, вы должны иметь возможность наблюдать за получением сообщения в экземпляре приложения.
- Экземпляр приложения в фоновом режиме

- Экземпляр приложения в фоновом режиме

- Бонус: Попробуйте отписаться от темы, в которую вы отправили сообщение, и отправить его повторно. Вы заметите, что сообщение не доставляется в экземпляр приложения.
8. Отправка первого сообщения об условиях темы.
Функция «Условия темы» позволяет отправлять сообщения по комбинации тем, что дает возможность более точно определять целевую аудиторию.
Например, в нашем приложении StockNews рассмотрим возможность отправки сообщений группе пользователей, подписанных на темы «Технологии» или «Автомобили». Подобный случай может произойти, например, в случае важного события, связанного с компанией Waymo.
Функция «Темы» позволяет выразить вашу комбинацию в виде логического выражения, используя следующие операторы.
- && : Логическое И. Например,
'Technology' in topics && 'Automotive' in topics— Нацеливается только на те экземпляры приложения, которые подписаны как на темы «Технологии», так и на темы «Автомобили». - || : Логическое ИЛИ. Например,
'Technology' in topics || 'Automotive' in topics— Нацеливается на экземпляры приложений, подписанные либо на темы «Технологии», либо на темы «Автомобили». - () : Скобки для группировки. Например,
'Technology' in topics && ('Automotive' in topics || 'Energy' in topics)- Нацеливается только на экземпляры приложений, подписанные на темы «Технологии» и либо «Автомобильная промышленность», либо «Энергетика».
Подробнее о том, как создавать запросы на отправку для использования этой функциональности, можно прочитать здесь.
Реализовать интеграцию на стороне сервера для отправки сообщения об условиях темы.
- Вернитесь в код сервера, перейдите в файл
FcmSender.javaи найдите метод с именемsendMessageToFcmTopicCondition.

- В первой строке для переменной
topicConditionукажите условие темы, на которую вы хотите отправить сообщение. Вы можете установить его следующим образом:'Technology' in topics && 'Automotive' in topics. - В следующих строках создайте новый объект
message(аналогичный тому, который определен в функцииsendMessageToFcmTopic).- Разница будет заключаться в том, что вместо установки поля
Topicобъекта вы будете устанавливать полеCondition.
- Разница будет заключаться в том, что вместо установки поля
Message message = Message.builder()
.putData("FOOCAR", "$500")
.setNotification(
Notification.builder()
.setTitle("Foo Car shows strong Q2 results")
.setBody("Foo Car crosses 1B miles. Stocks rally.")
.build())
.setCondition(topicCondition)
.build();
- Теперь добавьте вызов к экземпляру
FirebaseMessagingдля отправки сообщения (идентичный вызову send, выполненному в функцииsendMessageToFcmTopic).
FirebaseMessaging.getInstance().send(message);
- Наконец, обновите
mainфункцию и включите возможность вызова только функцииsendMessageToFcmTopicCondition.

Отправьте сообщение и подтвердите получение.
- Перед отправкой сообщения по теме убедитесь, что ваш экземпляр приложения удовлетворяет указанному условию темы, подписавшись на темы «Технологии» и «Автомобильная промышленность».
- Теперь вы можете отправить сообщение с вашей темой, выполнив
mainфункцию файлаFcmSender.java. - Как и прежде, вы должны иметь возможность увидеть подтверждение получения сообщения в экземпляре приложения.
- Экземпляр приложения в фоновом режиме

- Экземпляр приложения в фоновом режиме

- Бонус: Теперь вы можете отписаться от темы «Технологии» и повторно отправить сообщение об условии темы. Обратите внимание, что приложение не получит это сообщение.
9. Подведение итогов
Давайте вкратце повторим то, что вы уже изучили к этому моменту.
- Как инициировать подписку/отписку от темы из экземпляра приложения.
- Отправка сообщения в тему и проверка получения в подписанных экземплярах приложения.
- Отправка сообщения в тему «Условие» и проверка получения на экземпляре приложения, удовлетворяющем условию.
В следующем разделе вы узнаете, как можно подписывать/отписывать экземпляры приложения от тем без необходимости инициировать вызовы со стороны клиента.

10. Управление подписками на темы на стороне сервера.
До настоящего момента в этом практическом занятии все вызовы подписки и отписки от тем инициировались из экземпляра приложения.
Однако в некоторых случаях может потребоваться управление подписками на темы на стороне сервера. Например, может возникнуть необходимость подписать подгруппу существующих пользователей на новую тему, не дожидаясь развертывания приложения.
В этом разделе вы узнаете, как использовать Firebase Admin SDK для подписки и отписки пакета регистрационных токенов FCM от темы путем выполнения запросов на стороне сервера.
Реализовать серверную подписку на токены регистрации FCM в топик FCM.
- В серверном коде перейдите в класс
FcmSubscriptionManager.java. Найдите методsubscribeFcmRegistrationTokensToTopic. Здесь вы реализуете вызов APIsubscribeToTopic.

- Давайте подпишем экземпляр приложения на тему Energy. Для этого сначала предоставим данные для следующих двух полей:
-
registrationTokens: список строк, разделенных запятыми, представляющих токены регистрации FCM, для которых вы хотите создать подписки на темы. -
topicName: имя темы для раздела «Энергетика», например,/topics/Energy.
-
- В следующих нескольких строках реализуйте вызов следующим образом:
TopicManagementResponse response = FirebaseMessaging.getInstance().subscribeToTopic(
registrationTokens, topicName);
- Вы можете просмотреть
TopicManagementResponseчтобы получить некоторые общие статистические данные. Например, вывести количество успешно созданных подписок на темы с помощьюgetSuccessCount.
System.out.printf("Num tokens successfully subscribed %d", response.getSuccessCount());
- Наконец, в
mainфункции разрешите вызовы только функцииsubscribeFcmRegistrationTokensToTopic.
Создайте подписку и отправьте сообщение по теме.
- На этом этапе вы готовы создать подписку на тему и отправить ей сообщение.
- Выполните
mainфункцию классаFcmSubscriptionManager.java. Это создаст подписку на тему. - Теперь настройте код для отправки сообщения. Аналогично предыдущему,
- В файле
FcmSender.javaнайдите функциюsendMessageToFcmTopic. - Установите
topicNameна тему «Энергетика», например,/topics/Energy. - Создайте объект
Messageи свяжите его с темой, используяsetTopic. - Наконец, обновите
mainметод, чтобы включить только функциюsendMessageToFcmTopic.
- В файле
- Выполните
mainфункцию файлаFcmSender.java. Это отправит сообщение экземпляру вашего приложения, и вы сможете наблюдать за ним в своем приложении следующим образом.- Экземпляр приложения в фоновом режиме

- Экземпляр приложения в фоновом режиме

Реализовать отписку регистрационных токенов FCM от темы FCM на стороне сервера.
- Для отмены подписки на темы на стороне сервера используйте API
unsubscribeFromTopic. Вам нужно будет добавить соответствующий код в функциюunsubscribeFcmRegistrationTokensFromTopicклассаFcmSubscriptionManager.java.

- Реализация серверного кода для отмены подписки и проверка его эффективности путем отправки сообщения в тему — это задание, которое вы можете выполнить самостоятельно.
11. Поздравляем!
Поздравляем, вы успешно использовали темы FCM для отправки многоадресных сообщений подгруппам экземпляров вашего приложения. Это поможет упростить своевременное информирование пользователей о важном контенте.

Что дальше?
Теперь, когда вы завершили свою практическую работу, попробуйте изучить темы для других платформ, используя следующие руководства:

