Send Topic Messages with Firebase Console

Based on the publish/subscribe model, FCM topic messaging allows you to send a message to multiple devices that have opted in to a particular topic. You compose topic messages as needed, and FCM handles routing and delivering the message reliably to the right devices.

For example, users of a local weather forecasting app could opt in to a "severe weather alerts" topic and receive notifications of storms threatening specified areas. Users of a sports app could subscribe to automatic updates in live game scores for their favorite teams.

Some things to keep in mind about topics:

  • Topic messaging supports unlimited topics and subscriptions for each app.
  • Topic messaging is best suited for content such as news, weather, or other publicly available information.
  • Topic messages are optimized for throughput rather than latency. For fast, secure delivery to single devices or small groups of devices, target messages to registration tokens, not topics.
  • If you need to send messages to multiple devices per user, consider device group messaging for those use cases.

Set up the SDK

This section covers tasks you may have completed if you have already enabled other Firebase features for your app.

Prerequisites

  • A device running Android 4.0 (Ice Cream Sandwich) or newer, and Google Play services 10.2.0 or higher
  • The Google Play services SDK from the Google Repository, available in the Android SDK Manager
  • The latest version of Android Studio, version 1.5 or higher

If you don't have an Android Studio project already, you can download one of our quickstart samples if you just want to try a Firebase feature. If you're using a quickstart, remember to get the application ID from the build.gradle file in your project's module folder (typically app/), as you'll need this package name for the next step.

Add Firebase to your app

To add Firebase to your app you'll need a Firebase project and a Firebase configuration file for your app.

  1. Create a Firebase project in the Firebase console, if you don't already have one. If you already have an existing Google project associated with your mobile app, click Import Google Project. Otherwise, click Create New Project.
  2. Click Add Firebase to your Android app and follow the setup steps. If you're importing an existing Google project, this may happen automatically and you can just download the config file.
  3. When prompted, enter your app's package name. It's important to enter the package name your app is using; this can only be set when you add an app to your Firebase project.
  4. At the end, you'll download a google-services.json file. You can download this file again at any time.
  5. If you haven't done so already, copy this into your project's module folder, typically app/.

Add the SDK

If you would like to integrate the Firebase libraries into one of your own projects, you need to perform a few basic tasks to prepare your Android Studio project. You may have already done this as part of adding Firebase to your app.

First, add rules to your root-level build.gradle file, to include the google-services plugin:

buildscript {
    // ...
    dependencies {
        // ...
        classpath 'com.google.gms:google-services:3.0.0'
    }
}

Then, in your module Gradle file (usually the app/build.gradle), add the apply plugin line at the bottom of the file to enable the Gradle plugin:

apply plugin: 'com.android.application'

android {
  // ...
}

dependencies {
  // ...
  compile 'com.google.firebase:firebase-core:10.2.0'
  
  // Getting a "Could not find" error? Make sure you have
  // the latest Google Repository in the Android SDK manager
}

// ADD THIS AT THE BOTTOM
apply plugin: 'com.google.gms.google-services'

You should also add the dependencies for the Firebase SDKs you want to use. We recommend starting with com.google.firebase:firebase-core, which provides Firebase Analytics functionality. See the list of available libraries.

Receive topic messages on an Android client app

Once you've completed the setup tasks, you can add client code to subscribe to a topic and then handle messages sent to the topic.

Client apps can subscribe to any existing topic, or they can create a new topic. When a client app subscribes to a new topic name (one that does not already exist for your Firebase project), a new topic of that name is created in FCM and any client can subsequently subscribe to it.

To subscribe to a topic, the client app calls Firebase Cloud Messaging subscribeToTopic() with the FCM topic name:

FirebaseMessaging.getInstance().subscribeToTopic("news");

To unsubscribe, the client app calls Firebase Cloud Messaging unsubscribeFromTopic() with the topic name.

Send topic messages from the Notifications console

  1. Install and run the app on the target device(s).

  2. Open the **Notifications** tab of the Firebase console and select New Message.

  3. Enter message text
  4. From the topics list, select the topic you want to target. This list is populated with all topics with active subscriptions in this Firebase project (there may be a delay of as much as one day before new topics are displayed in the console).

After you click Send Message, Firebase Cloud Messaging delivers the message to all client app instances that are subscribed to the topic.

Console fields and the message payload

When you send a notification message from the Notifications console, Google uses the fields entered in the composer in two ways:

  1. Fields like User segment and Expires determine the message target and delivery options.
  2. Fields like Message text and Custom data are sent to the client in a payload comprised of key/value pairs.

Some of these latter keys are also available through the FCM server API. For example, key/value pairs entered in Custom data are handled as a data payload for the notification. Other fields map directly to keys in the FCM notification payload.

Note that some Notifications console fields are not available through the FCM server API. For example, you can target user segments based on app, app version, or language in ways that are not available using the to field in the server API.

The keys that the Notifications console sends to clients are:

Key Console field label Description
notification.title Message title Indicates notification title.
notification.body Message text Indicates notification body text.
data Custom data Key/value pairs that you define. These are delivered as a data payload for the app to handle.

Keys that determine message delivery include:

Key Console field label Description
priority Priority

Sets the priority of the message.

For more information, see Setting the priority of a message.

sound Sound

Indicates a sound to play when the device receives a notification.

time_to_live Expires

This parameter specifies how long (in seconds) the message should be kept in FCM storage if the device is offline. For more information, see Setting the lifespan of a message.

Send feedback about...

Need help? Visit our support page.