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 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 нажмите «Добавить проект» , назовите проект Firebase StockNews и нажмите «Продолжить». Примечание. Запомните идентификатор проекта Firebase (или щелкните значок «Изменить» , чтобы установить предпочтительный идентификатор проекта).
- Вы можете пропустить включение 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
также предоставляется классApplication
Android с именем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
.
Представление проекта на левой панели навигации должно выглядеть примерно так:
Обратите внимание: IntelIj 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, которая позволит Firebase-admin SDK авторизовать вызовы API-интерфейсов FCM.
- Перейдите в консоль Firebase, щелкните значок шестеренки рядом с пунктом «Обзор проекта» на левой панели навигации и выберите «Настройки проекта» .
- На странице настроек выберите «Учетные записи служб» и нажмите «Создать учетную запись службы» .
- Теперь нажмите кнопку «Создать новый закрытый ключ» , и начнется автоматическая загрузка файла ключа.
- Переименуйте файл ключа в
service-account.json
и скопируйте его в папкуmessaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources
. - И
FcmSender.java
, иFcmSubscriptionManager.java
загружают файлservice-account.json
из пути к классам, используя следующий код.
- На этом этапе серверный код готов. Запустите 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
для отправки сообщения (идентичный вызову отправки, выполненному в функции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
.
- Давайте подпишем экземпляр приложения на тему 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
темы Energy, т. е./topics/Energy
. - Создайте объект
Message
и нацельте его на тему с помощьюsetTopic
. - Наконец, обновите
main
метод, чтобы включить только функциюsendMessageToFcmTopic
.
- В
- Выполните
main
функциюFcmSender.java
. Это отправит сообщение в экземпляр вашего приложения, и вы сможете наблюдать его в своем приложении следующим образом.- Экземпляр приложения на переднем плане
- Экземпляр приложения в фоновом режиме
Внедрить отписку регистрационных токенов FCM на стороне сервера в теме FCM.
- Для отмены подписки на темы на стороне сервера используйте API
unsubscribeFromTopic
. Вы добавите соответствующий код в функциюunsubscribeFcmRegistrationTokensFromTopic
классаFcmSubscriptionManager.java
.
- Реализация кода отказа от подписки на стороне сервера и проверка его эффекта путем отправки тематического сообщения оставлены для вас в качестве упражнения.
11. Поздравления
Поздравляем, вы успешно использовали темы FCM для отправки многоадресных сообщений подгруппам экземпляров вашего приложения. Это поможет вам упростить своевременную доставку пользователям соответствующего контента.
Что дальше?
Теперь, когда вы завершили работу над кодом, рассмотрите возможность опробовать темы для других платформ, используя следующие руководства: