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 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 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. Acesse 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 (plat_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.

   O que é um nome de pacote e onde ele pode ser encontrado?

   • Um nome de pacote identifica seu app de forma exclusiva no dispositivo e na Google Play Store.

   • Um nome de pacote é frequentemente chamado de ID do aplicativo.

   • Encontre o nome do pacote do app no arquivo Gradle do módulo (nível do app), geralmente app/build.gradle (exemplo de nome do pacote: com.yourcompany.yourproject).

   • Saiba que o valor do nome do pacote diferencia maiúsculas de minúsculas e não pode ser alterado no app Android do Firebase depois de ser registrado no projeto.

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

   Como o apelido do app e o certificado de assinatura SHA-1 de depuração são usados no Firebase?

   • Apelido do app: um prático identificador interno que só é visível para você no Console do Firebase.

   • Certificado de assinatura SHA-1 de depuração: um hash SHA-1 é exigido pelo Firebase Authentication (ao usar o Login do Google ou o login com número de telefone) e pelo Firebase Dynamic Links.

5. Clique em Registrar app.

Adicionar um arquivo de configuração do Firebase

1. Faça o download e adicione ao seu app o arquivo de configuração do Firebase para Android (google-services.json):

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

   2. Mova esse arquivo para o diretório raiz do módulo (nível do app) do seu aplicativo.

   O que preciso saber sobre esse arquivo de configuração?

   • O arquivo de configuração do Firebase contém identificadores exclusivos, mas não secretos, para seu projeto. Para saber mais sobre esse arquivo de configuração, acesse Noções básicas sobre projetos do Firebase.

   • É possível fazer o download do arquivo de configuração do Firebase novamente a qualquer momento.

   • Verifique se outros caracteres, como (2), não foram adicionados ao final do nome do arquivo de configuração.

2. Para permitir que os SDKs do Firebase acessem os valores no seu arquivo de configuração google-services.json, você precisa do plug-in do Gradle para Serviços do Google (google-services).

   1. No arquivo Gradle no nível raiz do projeto (<project>/build.gradle), adicione o plug-in dos Serviços do Google como uma dependência do buildscript:

      buildscript {
      
          repositories {
            // Make sure that you have the following two repositories
            google()  // Google's Maven repository
            mavenCentral()  // Maven Central repository
          }
      
          dependencies {
            ...
      
            // Add the dependency for the Google services Gradle plugin
            classpath 'com.google.gms:google-services:4.3.13'
          }
      }
      
      allprojects {
        ...
      
        repositories {
          // Make sure that you have the following two repositories
          google()  // Google's Maven repository
          mavenCentral()  // Maven Central repository
        }
      }
      

   2. No arquivo Gradle do módulo (nível do app) (geralmente <project>/<app-module>/build.gradle), adicione o plug-in dos Serviços do Google:

      plugins {
          id 'com.android.application'
      
          // Add the Google services Gradle plugin
          id 'com.google.gms.google-services'
          ...
      }
      

Adicionar SDKs do Firebase ao seu app

1. No arquivo Gradle do módulo (nível do app) (geralmente <project>/<app-module>/build.gradle), adicione a dependência da biblioteca Android do Firebase Cloud Messaging. Para gerenciar o controle de versões das bibliotecas, recomendamos usar a BoM do Firebase para Android.

   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.4.0')
   
       // Add 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 vai usar versões compatíveis das bibliotecas Android do Firebase.

   (Alternativa) Adicionar dependências das bibliotecas do Firebase sem usar a BoM

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

   Se você usa várias bibliotecas do Firebase no seu app, recomendamos utilizar a BoM para gerenciar as versões dessas bibliotecas, o que ajuda a garantir a compatibilidade de todas elas.

   dependencies {
       // Add 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.8'
       implementation 'com.google.firebase:firebase-analytics:21.1.1'
   }
   

   Kotlin+KTX

   dependencies {
       // Import the BoM for the Firebase platform
       implementation platform('com.google.firebase:firebase-bom:30.4.0')
   
       // Add 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 vai usar versões compatíveis das bibliotecas Android do Firebase.

   (Alternativa) Adicionar dependências das bibliotecas do Firebase sem usar a BoM

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

   Se você usa várias bibliotecas do Firebase no seu app, recomendamos utilizar a BoM para gerenciar as versões dessas bibliotecas, o que ajuda a garantir a compatibilidade de todas elas.

   dependencies {
       // Add 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.8'
       implementation 'com.google.firebase:firebase-analytics-ktx:21.1.1'
   }
   

2. Sincronize seu projeto do Android com os arquivos Gradle.

   Você está recebendo uma falha de compilação sobre o suporte a invoke-custom e sobre a ativação da simplificação? Veja como corrigir isso.

   Builds do Gradle que usam o Plug-in do Android para Gradle (AGP) v4.2 ou anterior precisam dar suporte a Java 8. Caso contrário, esses projetos Android receberão uma falha de compilação ao adicionar um SDK do Firebase.

   Para corrigir essa falha de compilação, use uma destas duas opções:

   • Adicione o compileOptions listado da mensagem de erro ao seu arquivo build.gradle no nível do app.
   • Aumente a minSdkVersion do seu projeto Android para 26 ou mais.

   Saiba mais sobre essa falha de compilação nestas Perguntas frequentes.

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():

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();
        }
    });

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.

/**
 * 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

/**
 * 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) de 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:

• Receber mensagens em um app para Android
• Enviar mensagens a vários dispositivos