Эта страница переведена с помощью Cloud Translation API.

Ваше первое многоадресное push-сообщение с использованием тем FCM

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 .
1. Указанное здесь имя пакета должно совпадать с именем, указанным в AndroidManifest.xml вашего стартового кода StockNewsApp . Если вы хотите найти или изменить его, выполните следующие действия:
  1. В каталоге StockNewsApp откройте файл app/src/main/AndroidManifest.xml .
  2. В элементе manifest найдите строковое значение атрибута package . Это значение является именем пакета Android.

В диалоговом окне 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 и зарегистрирует его. Однако в пользовательском интерфейсе приложения ничего не изменится.
1. Скопируйте и сохраните регистрационный токен 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.
1. Перейдите в консоль Firebase, щелкните значок шестеренки рядом с пунктом «Обзор проекта» на левой панели навигации и выберите «Настройки проекта» .
2. На странице настроек выберите « Учетные записи служб» и нажмите «Создать учетную запись службы» .
3. Теперь нажмите кнопку «Создать новый закрытый ключ» , и начнется автоматическая загрузка файла ключа.
4. Переименуйте файл ключа в service-account.json и скопируйте его в папку messaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources .
5. И FcmSender.java , и FcmSubscriptionManager.java загружают файл service-account.json из пути к классам, используя следующий код.
На этом этапе серверный код готов. Запустите Build -> Build Project из верхней строки меню.

Отправка тестового сообщения

В FcmSender.java найдите функцию sendMessageToFcmRegistrationToken и вставьте регистрационный токен FCM, скопированный из раздела «Запуск стартового приложения», в поле registrationToken .
В main функции раскомментируйте только функцию sendMessageToFcmRegistrationToken и нажмите «Выполнить», чтобы выполнить код.
1. Обратите внимание, как токен регистрации FCM устанавливается в поле Token объекта message .
2. Кроме того, обратите внимание, как мы использовали API send интерфейса FirebaseMessaging .

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

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

Отлично, вы использовали 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 .

Отправьте сообщение и подтвердите получение

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

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 ).
1. Разница будет заключаться в том, что вместо установки поля 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 .
Как и раньше, вы сможете наблюдать за получением сообщения в экземпляре приложения.
1. Экземпляр приложения на переднем плане
1. Экземпляр приложения в фоновом режиме
Бонус: теперь вы можете отказаться от подписки на тему «Технологии» и повторно отправить сообщение о состоянии темы. Вы должны заметить, что сообщение не получено экземпляром приложения.

9. Подведение итогов

Давайте кратко подведем итог тому, что вы узнали к этому моменту.

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

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

10. Управление подписками на темы со стороны сервера

До сих пор в этой кодовой лаборатории все вызовы подписок и отписок на темы инициируются из экземпляра приложения.

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

В этом разделе вы узнаете, как использовать Firebase Admin SDK для подписки и отмены подписки на пакет регистрационных токенов FCM на тему, совершая вызовы со стороны сервера.

Реализация подписки на регистрационные токены FCM на стороне сервера в теме FCM.

В коде сервера перейдите к классу FcmSubscriptionManager.java . Найдите метод subscribeFcmRegistrationTokensToTopic . Здесь вы реализуете вызов API subscribeToTopic .

Давайте подпишем экземпляр приложения на тему Energy. Для этого сначала предоставьте данные для следующих двух полей:
1. registrationTokens : разделенный запятыми список строк, представляющих регистрационные токены FCM, для которых вы хотите создать подписки на темы.
2. 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 . Это создаст подписку на тему.
Теперь настройте код для отправки сообщения. Подобно тому, как раньше,
1. В FcmSender.java найдите функцию sendMessageToFcmTopic .
2. Задайте в topicName темы Energy, т. е. /topics/Energy .
3. Создайте объект Message и нацельте его на тему с помощью setTopic .
4. Наконец, обновите main метод, чтобы включить только функцию sendMessageToFcmTopic .
Выполните main функцию FcmSender.java . Это отправит сообщение в экземпляр вашего приложения, и вы сможете наблюдать его в своем приложении следующим образом.
1. Экземпляр приложения на переднем плане
1. Экземпляр приложения в фоновом режиме

Внедрить отписку регистрационных токенов FCM на стороне сервера в теме FCM.

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

Реализация кода отказа от подписки на стороне сервера и проверка его эффекта путем отправки тематического сообщения оставлены для вас в качестве упражнения.

11. Поздравления

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

Что дальше?

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

Справочная документация

Справочник по API Android ( Java / Kotlin )
Справочник по API iOS ( ObjectiveC / Swift )
Справочник по API Javascript ( версия 9 / версия 8 )
Справочник по Admin SDK ( Node.js / Java / Python / .NET )