Configurar um app cliente do Firebase Cloud Messaging no Android

Para criar um app cliente do Firebase Cloud Messaging para Android, use a API FirebaseMessaging e o Android Studio 1.4 ou mais recente com Gradle. Para seguir as instruções desta página, conclua as etapas para adicionar o Firebase ao seu projeto do Android.

Os clientes do FCM exigem que dispositivos com o Android 4.4 ou versões mais recentes também tenham o app Google Play Store instalado ou um emulador executando o Android 4.4 com APIs do Google. Não é necessário se limitar à Google Play Store para implantar apps Android.

Configurar o SDK

Esta seção aborda tarefas que você talvez tenha realizado se já ativou outros recursos do Firebase para seu app.

Antes de começar

  • Instale ou atualize o Android Studio para a versão mais recente.

  • Verifique se o projeto atende a estes requisitos:

    • O nível desejado da API é o 19 (KitKat) ou um superior
    • Usa o Android 4.4 ou versões mais recentes
    • Usa o Jetpack (AndroidX), que inclui o cumprimento dos seguintes requisitos de versão:
      • com.android.tools.build:gradle v3.2.1 ou mais recente
      • compileSdkVersion 28 ou mais recente

  • Configure um dispositivo físico ou use um emulador para executar o app.
    Os SDKs do Firebase com uma dependência no Google Play Services exigem que o dispositivo ou o emulador tenham o Google Play Services instalado.

  • Faça login no Firebase com sua Conta do Google.

Se você ainda não tem um projeto Android, mas quer testar um produto do Firebase, faça o download de uma das nossas amostras introdutórias.

Criar um projeto do Firebase

Antes de adicionar o Firebase ao app Android, é preciso criar um projeto do Firebase para então conectá-lo ao app. Visite Noções básicas sobre projetos do Firebase para saber mais.

Registrar o app no Firebase

Para usar o Firebase no seu app Android, é necessário registrá-lo no projeto do Firebase. Registrar o app também quer dizer "adicionar" o app ao projeto.

  1. Acesse o Console do Firebase.

  2. No centro da página de visão geral do projeto, clique no ícone do Android () ou em Adicionar app para iniciar o fluxo de trabalho de configuração.

  3. Digite o nome do pacote do app no campo Nome do pacote Android.

  4. (Opcional) Insira outras informações do aplicativo: apelido do app e certificado de assinatura SHA-1 de depuração.

  5. Clique em Registrar app.

Adicionar um arquivo de configuração do Firebase

  1. Para adicionar o arquivo de configuração do Firebase para Android ao app, siga estas etapas:

    1. Clique em Fazer o download do google-services.json para receber o arquivo de configuração do Firebase para Android (google-services.json).

    2. Mova seu arquivo de configuração para o diretório de módulos do seu app.

  2. Para ativar os produtos do Firebase no app, adicione o plug-in google-services aos seus arquivos do Gradle.

    1. No arquivo do Gradle (build.gradle) no nível raiz, adicione regras para incluir o plug-in de Serviços do Google para Gradle. Verifique se você tem o repositório Maven do Google também.

      buildscript {

  repositories {
    // Check that you have the following line (if not, add it):
    google()  // Google's Maven repository
  }

  dependencies {
    // ...

    // Add the following line:
    classpath 'com.google.gms:google-services:4.3.10'  // Google Services plugin
  }
}

allprojects {
  // ...

  repositories {
    // Check that you have the following line (if not, add it):
    google()  // Google's Maven repository
    // ...
  }
}

    2. No seu arquivo Gradle do módulo (nível do app) (geralmente app/build.gradle), aplique o plug-in de Serviços do Google para Gradle:

      apply plugin: 'com.android.application'
// Add the following line:
apply plugin: 'com.google.gms.google-services'  // Google Services plugin

android {
  // ...
}

Adicionar SDKs do Firebase ao app

  1. Usando a BoM do Firebase para Android, declare a dependência da biblioteca do Android do Firebase Cloud Messaging no arquivo do Gradle (nível do app) do módulo, que geralmente é app/build.gradle.

    Para uma experiência ideal com o Firebase Cloud Messaging, recomendamos ativar o Google Analytics no seu projeto e adicionar o SDK do Firebase para Analytics ao seu app.

    Java 

    dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:29.0.3')

    // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-messaging'
    implementation 'com.google.firebase:firebase-analytics'
}

    Ao usar a BoM do Firebase para Android, seu app sempre usará versões compatíveis das bibliotecas do Firebase para Android.

    (Alternativa) Declare as dependências das bibliotecas do Firebase sem usar a BoM.

    Se você preferir não usar a BoM do Firebase, especifique cada versão das bibliotecas do Firebase na linha de dependência correspondente.

    Caso você use várias bibliotecas do Firebase no seu app, recomendamos usar a BoM para gerenciar versões de bibliotecas, o que garante a compatibilidade de todas as versões.. 

    dependencies {
    // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-messaging:23.0.0'
    implementation 'com.google.firebase:firebase-analytics:20.0.2'
}

    Kotlin+KTX 

    dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:29.0.3')

    // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-messaging-ktx'
    implementation 'com.google.firebase:firebase-analytics-ktx'
}

    Ao usar a BoM do Firebase para Android, seu app sempre usará versões compatíveis das bibliotecas do Firebase para Android.

    (Alternativa) Declare as dependências das bibliotecas do Firebase sem usar a BoM.

    Se você preferir não usar a BoM do Firebase, especifique cada versão das bibliotecas do Firebase na linha de dependência correspondente.

    Caso você use várias bibliotecas do Firebase no seu app, recomendamos usar a BoM para gerenciar versões de bibliotecas, o que garante a compatibilidade de todas as versões.

    dependencies {
    // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-messaging-ktx:23.0.0'
    implementation 'com.google.firebase:firebase-analytics-ktx:20.0.2'
}

  2. Sincronize seu app para garantir que todas as dependências tenham as versões necessárias.

Editar o manifesto do app

Adicione os seguintes itens ao manifesto do app:

  • Um serviço que estende FirebaseMessagingService. Isso é necessário se você quiser processar qualquer mensagem além de simplesmente receber notificações em apps em segundo plano. Para receber notificações em apps em primeiro plano ou payload de dados, enviar mensagens upstream e assim por diante, você precisa estender esse serviço.
    • <service
    android:name=".java.MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>
    AndroidManifest.xml
  • (Opcional) Elementos de metadados dentro do componente do aplicativo para definir um ícone e uma cor padrão para notificações. O Android usa esses valores sempre que as mensagens recebidas não definem explicitamente o ícone ou a cor dele.
    • <!-- Set custom default icon. This is used when no icon is set for incoming notification messages.
     See README(https://goo.gl/l4GJaQ) for more. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_stat_ic_notification" />
<!-- Set color used with incoming notification messages. This is used when no color is set for the incoming
     notification message. See README(https://goo.gl/6BKBk7) for more. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/colorAccent" />
    AndroidManifest.xml
  • (Opcional) A partir do Android 8.0 (nível API 26) e posterior, os canais de notificação são aceitos e recomendados. O FCM oferece um canal de notificação padrão com configurações básicas. Se você preferir criar e usar seu próprio canal padrão, defina default_notification_channel_id como o ID do objeto do canal de notificação, conforme mostrado. O FCM usará esse valor sempre que as mensagens recebidas não definirem explicitamente um canal de notificação. Para saber mais, consulte Gerenciar canais de notificação. 
    • <meta-data
    android:name="com.google.firebase.messaging.default_notification_channel_id"
    android:value="@string/default_notification_channel_id" />
    AndroidManifest.xml

Acessar o token de registro do dispositivo

Na primeira inicialização do app, o SDK do FCM gera um token de registro para a instância do app cliente. Se o objetivo for dispositivos individuais ou criar grupos de dispositivos, você precisará acessar esse token estendendo FirebaseMessagingService e modificando onNewToken.

Veja nesta seção como recuperar o token e monitorar as alterações feitas nele. Como o token pode ser alternado após a primeira inicialização, recomendamos que você recupere o token de registro mais atualizado.

Esse token pode mudar quando:

  • o app é restaurado em um novo dispositivo;
  • o usuário desinstala/reinstala o app;
  • o usuário limpa os dados do app.

Recuperar o token de registro atual

Quando você precisar recuperar o token atual, chame FirebaseMessaging.getInstance().getToken():

Java

FirebaseMessaging.getInstance().getToken()
    .addOnCompleteListener(new OnCompleteListener<String>() {
        @Override
        public void onComplete(@NonNull Task<String> task) {
          if (!task.isSuccessful()) {
            Log.w(TAG, "Fetching FCM registration token failed", task.getException());
            return;
          }

          // Get new FCM registration token
          String token = task.getResult();

          // Log and toast
          String msg = getString(R.string.msg_token_fmt, token);
          Log.d(TAG, msg);
          Toast.makeText(MainActivity.this, msg, Toast.LENGTH_SHORT).show();
        }
    });

Kotlin+KTX

FirebaseMessaging.getInstance().token.addOnCompleteListener(OnCompleteListener { task ->
    if (!task.isSuccessful) {
        Log.w(TAG, "Fetching FCM registration token failed", task.exception)
        return@OnCompleteListener
    }

    // Get new FCM registration token
    val token = task.result

    // Log and toast
    val msg = getString(R.string.msg_token_fmt, token)
    Log.d(TAG, msg)
    Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show()
})

Monitorar a geração de tokens

O retorno de chamada onNewToken é acionado sempre que um novo token é gerado.

Java

/**
 * There are two scenarios when onNewToken is called:
 * 1) When a new token is generated on initial app startup
 * 2) Whenever an existing token is changed
 * Under #2, there are three scenarios when the existing token is changed:
 * A) App is restored to a new device
 * B) User uninstalls/reinstalls the app
 * C) User clears app data
 */
@Override
public void onNewToken(String token) {
    Log.d(TAG, "Refreshed token: " + token);

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token);
}
MyFirebaseMessagingService.java

Kotlin+KTX

/**
 * Called if the FCM registration token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the
 * FCM registration token is initially generated so this is where you would retrieve the token.
 */
override fun onNewToken(token: String) {
    Log.d(TAG, "Refreshed token: $token")

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token)
}
MyFirebaseMessagingService.kt

Quando receber o token, você poderá enviá-lo ao servidor do app e armazená-lo usando o método de sua preferência.

Verificar o Google Play Services

Os apps que contam com o SDK do Google Play Services devem sempre verificar se há um APK do Google Play Services compatível no dispositivo antes de acessar os recursos. Recomenda-se fazer isso em dois lugares: no método onCreate() da atividade principal e no método onResume(). Com a verificação de onCreate(), só é possível utilizar o app após uma verificação bem-sucedida. A verificação de onResume() garante que, se o usuário retornar ao app em execução por outro meio, como pelo botão "Voltar", a verificação ainda será executada.

Se o dispositivo não tiver uma versão compatível do Google Play Services, o app poderá chamar GoogleApiAvailability.makeGooglePlayServicesAvailable() para permitir que os usuários façam o download do Google Play Services na Play Store.

Impedir a inicialização automática

Quando um token de registro do FCM é gerado, a biblioteca faz upload dos dados de configuração e do identificador para o Firebase. Se você preferir evitar a geração automática de tokens, desative a coleta automática do Analytics e a inicialização automática do FCM (é necessário desativar ambas) adicionando estes valores de metadados ao seu AndroidManifest.xml:

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />
AndroidManifest.xml

Para reativar o início automático do FCM, faça uma chamada de ambiente de execução:

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);
MainActivity.java

Kotlin+KTX

Firebase.messaging.isAutoInitEnabled = true
MainActivity.kt

Para reativar a coleta do Analytics, chame o método setAnalyticsCollectionEnabled() da classe FirebaseAnalytics. Por exemplo:

setAnalyticsCollectionEnabled(true);

Depois de definidos, esses valores persistem após a reinicialização do app.

Próximas etapas

Depois que o app cliente estiver configurado, é possível começar a enviar mensagens downstream com o Editor do Notificações. Essa funcionalidade é demonstrada na amostra introdutória, que você pode fazer o download, executar e avaliar.

Para adicionar outro comportamento mais avançado ao app, você pode declarar um filtro de intent e implementar uma atividade para responder a mensagens recebidas. Para ver mais detalhes, consulte os guias para envio de mensagens de um servidor de app:

É importante lembrar que, para aproveitar esses recursos, você precisará de uma implementação de servidor e dos protocolos do servidor (HTTP ou XMPP) ou de uma implementação do SDK Admin.