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 нажмите « Добавить проект» , назовите проект 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 Console, следуйте инструкциям по загрузке файла конфигурации
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
также предоставляется класс Android-Application
с именемStockNewsApplication
.- Этот класс будет первым, который будет создан при запуске приложения.
- В
StockNewsApplication
классаonCreate
добавлен вызов создания токена регистрации 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
из пути к классам, используя следующий код.
- Перейдите в консоль Firebase, щелкните значок шестеренки рядом с Обзором проекта на левой панели навигации и выберите Настройки проекта .
- На этом серверный код готов. Запустите Build -> Build Project из верхней строки меню.
Отправка тестового сообщения
- В
FcmSender.java
найдите функциюsendMessageToFcmRegistrationToken
и вставьте токенregistrationToken
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
вы реализуете вызов API-интерфейсаsubscribeToTopic
объекта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 : разделенный запятыми список строк, представляющих токены
registrationTokens
FCM, для которых вы хотите создать подписку на тему. -
topicName
: название темы для темы Energy, т.е./topics/Energy
.
- RegistrationTokens : разделенный запятыми список строк, представляющих токены
- В следующих нескольких строках реализуйте вызов в следующих строках:
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
класса FcmSubscriptionManager.java.
- Внедрение кода отказа от подписки на стороне сервера и проверка его действия путем отправки сообщения в тему остается вам в качестве упражнения.
11. Поздравления
Поздравляем, вы успешно использовали темы FCM для отправки многоадресных сообщений в подгруппы экземпляров вашего приложения. Это поможет вам упростить своевременную доставку релевантного контента вашим пользователям.
Что дальше?
Теперь, когда вы завершили свою лабораторию кода, подумайте о том, чтобы попробовать темы для других платформ, используя следующие руководства: