1. Введение
Цели
В этой лабораторной работе вы узнаете, как настроить ваше многоплатформенное приложение таким образом, чтобы вы могли осуществлять многоадресную рассылку push-сообщений различным подгруппам экземпляров вашего приложения с использованием тем FCM.
После завершения вы сможете использовать инфраструктуру FCM для управления этими подгруппами, а также для многоадресной рассылки push-сообщений по подгруппам.
Обзор тем
Темы — это поддерживаемый инфраструктурой FCM способ охвата подгрупп экземпляров вашего приложения сообщениями.
FCM предоставляет API для отправки сообщений и поддержки подписок на эти темы. Процессы привязки и отсоединения экземпляра приложения к теме называются подпиской и отменой подписки соответственно.
Темы следует использовать для общедоступного контента. Например, для сообщений о погоде. Если вы хотите отправлять конфиденциальные сообщения, используйте Firebase Admin SDK для многоадресной рассылки сообщений на несколько устройств .
Многоадресная рассылка на основе тем оптимизирована для обеспечения пропускной способности.
Чему вы научитесь
- Как подписать (и отписать) пользователей на темы из мобильного приложения.
- Как отправлять многоадресные push-сообщения с использованием тем.
- Как отправлять сообщения в несколько тем, используя условия тем.
- Как управлять подписками на темы на стороне сервера и выполнять массовые подписки и отписки.
Что вы построите
- Приложение для Android, которое подписывается/отписывается от тем и получает сообщения при их отправке в темы.
- Интеграция на стороне сервера с использованием Firebase Admin SDK, которая будет использоваться для отправки тематических сообщений через API FCM.
Что вам понадобится
- Браузер по вашему выбору, например Chrome.
- IntelliJ IDEA IDE для разработки приложений Java.
- Обязательно включите поддержку Gradle при установке.
- Android Studio IDE для разработки 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 (так называемая «Gemini в Firebase»).
- Для этой лабораторной работы вам не понадобится Google Analytics, поэтому отключите опцию 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 Console.
- Скопируйте файл
google-services.json
(который вы только что загрузили) в каталогmessaging/fcm-topics-codelab/starter/StockNewsApp/app
.
4. Создайте и запустите свое приложение.
Вы готовы приступить к работе над своим приложением! Для начала соберите и запустите приложение.
Импортируйте стартовое приложение
Запустите Android Studio и импортируйте messaging/fcm-topics-codelab/starter/StockNewsApp
из каталога начального кода.
После загрузки проекта вы также можете увидеть предупреждение о том, что Git не отслеживает все ваши локальные изменения. Нажмите « Игнорировать » или « X » в правом верхнем углу. (Никакие изменения не будут отправлены обратно в репозиторий 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
уже добавлена зависимость от Firebase-admin SDK . Этот SDK обеспечивает доступ к различным функциям отправки сообщений FCM.
- Наконец, есть два класса, а именно:
-
FcmSender.java
: Этот класс содержит следующие примечательные методы:-
initFirebaseSDK
: инициализирует firebase-admin SDK. -
sendMessageToFcmRegistrationToken
: отправка сообщения на регистрационный токен FCM. -
sendMessageToFcmTopic
: отправить сообщение в тему FCM. -
sendMessageToFcmTopicCondition
: отправить сообщение в тему FCM.
-
-
FcmSubscriptionManager.java
: Этот класс содержит методы, позволяющие управлять подписками на темы со стороны сервера.-
initFirebaseSDK
: инициализирует firebase-admin SDK. -
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, нажмите на значок шестеренки рядом с пунктом «Обзор проекта» на левой панели навигации и выберите «Настройки проекта» .
- На этом этапе серверный код готов. Выберите «Сборка» -> «Сборка проекта» в верхней строке меню.
Отправка тестового сообщения
- В
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 к соответствующей категории Stock.
Реализовать подписку на темы
- В методе
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
для отправки сообщения (идентично вызову отправки, выполненному в функцииsendMessageToFcmTopic
).
FirebaseMessaging.getInstance().send(message);
- Наконец, обновите
main
функцию и включите вызов только функцииsendMessageToFcmTopicCondition
.
Отправьте сообщение и подтвердите получение
- Перед отправкой сообщения по теме сначала убедитесь, что экземпляр вашего приложения удовлетворяет указанному условию темы, подписав экземпляр приложения на темы «Технологии» и «Автомобилестроение».
- Теперь вы можете отправить сообщение по теме, выполнив
main
функциюFcmSender.java
. - Как и прежде, вы сможете наблюдать получение сообщения в экземпляре приложения.
- Экземпляр приложения на переднем плане
- Экземпляр приложения в фоновом режиме
- Бонус: теперь вы можете отписаться от темы «Технологии» и повторно отправить сообщение о состоянии темы. Обратите внимание, что приложение не получит это сообщение.
9. Подведение итогов
Давайте сделаем краткий обзор того, что вы узнали на данный момент.
- Как инициировать подписку на тему/отписку от экземпляра приложения.
- Отправка сообщения в тему и проверка получения на подписанных экземплярах приложения.
- Отправка сообщения в тему «Условие» и проверка получения на экземпляре приложения, удовлетворяющем условию.
В следующем разделе вы узнаете, как можно подписывать/отменять подписку экземпляров приложения на темы без необходимости инициировать вызовы со стороны клиента.
10. Управление подписками на темы со стороны сервера
До сих пор в этой лабораторной работе все вызовы подписки и отмены подписки на темы инициировались из экземпляра приложения.
Однако в некоторых случаях может потребоваться управление подписками на темы на стороне сервера. Например, вам может понадобиться подписать подгруппу пользователей из вашей текущей базы на новую тему, не дожидаясь запуска приложения.
В этом разделе вы узнаете, как использовать Firebase Admin SDK для подписки и отмены подписки на пакет токенов регистрации FCM на тему, выполняя вызовы со стороны сервера.
Реализовать подписку на регистрационные токены FCM на стороне сервера в теме FCM
- В серверном коде перейдите к классу
FcmSubscriptionManager.java
. Найдите методsubscribeFcmRegistrationTokensToTopic
. Здесь вы реализуете вызов APIsubscribeToTopic
.
- Давайте подпишем экземпляр приложения на тему «Энергия». Для этого сначала предоставьте данные для следующих двух полей:
-
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 для многоадресной рассылки сообщений подгруппам ваших приложений. Это упростит вам возможность своевременно доставлять пользователям релевантный контент.
Что дальше?
Теперь, когда вы завершили работу над кодовой лабораторией, рассмотрите возможность попробовать темы для других платформ, используя следующие руководства: