Enviar uma mensagem de teste a um app em segundo plano

Para começar a usar o FCM, crie o caso de uso mais simples: enviar uma mensagem de notificação de teste do Editor do Notificações a um dispositivo de desenvolvimento específico quando o app estiver em segundo plano. Esta página descreve todas as etapas para fazer isso, desde a configuração até a verificação. Talvez ela aborde etapas que você já concluiu se tiver configurado um app cliente do Android para o FCM.

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 é 19 (KitKat) ou 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:30.1.0')

    // 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'
}

    Com 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 as versões dessas bibliotecas para garantir a compatibilidade de todas elas. 

    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.5'
    implementation 'com.google.firebase:firebase-analytics:21.0.0'
}

    Kotlin+KTX 

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

    // 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'
}

    Com 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 as versões dessas bibliotecas para garantir a compatibilidade de todas elas. 

    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.5'
    implementation 'com.google.firebase:firebase-analytics-ktx:21.0.0'
}

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

Acessar o token de registro

Para enviar uma mensagem a um dispositivo específico, é necessário saber o token de registro dele. Como você precisa informar o token em um campo do console do Notificações para concluir este tutorial, lembre-se de copiar ou armazenar o token em segurança depois de recuperá-lo.

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(@NonNull 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.

Enviar uma mensagem de notificação de teste

  1. Instale e execute o app no dispositivo de destino.

  2. Verifique se o app está em segundo plano no dispositivo.

  3. Abra o Editor do Notificações e selecione Nova notificação.

  4. Digite o texto da mensagem.

  5. Selecione Enviar mensagem de teste.

  6. No campo Adicionar um token de registro do FCM, insira o token de registro obtido na seção anterior deste guia.

  7. Clique em Testar.

Depois de clicar em Testar, o dispositivo cliente com o app em segundo plano receberá a notificação na bandeja de notificações do sistema.

Veja insights sobre a entrega de mensagens ao seu aplicativo no painel de relatórios do FCM, que registra o número de mensagens enviadas e abertas em dispositivos Apple e Android, além de dados de "impressões" (notificações vistas pelos usuários) para apps Android.

Próximas etapas

Enviar mensagens aos apps em primeiro plano

Depois de enviar com êxito mensagens de notificação enquanto o seu app está em segundo plano, consulte Receber mensagens em um app para Android para começar a enviar a apps em primeiro plano.

Vá além das mensagens de notificação

Para ir além das mensagens de notificação e adicionar outros comportamentos mais avançados ao seu app, consulte: