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.

  • Certifique-se de que seu projeto atenda aos seguintes requisitos (alguns produtos podem ter requisitos mais rigorosos):

    • Visa o nível 21 da API (Lollipop) ou mais recente.
    • Usa o Android 5.0 ou versões mais recentes
    • Usa o Jetpack (AndroidX), que inclui o cumprimento dos seguintes requisitos de versão:
      • com.android.tools.build:gradle v7.3.0 ou mais recente
      • compileSdkVersion 28 ou posterior

  • 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 () 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. 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.

  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.kts ou <project>/build.gradle), adicione o plug-in dos serviços do Google como uma dependência:

      Kotlin 

      plugins {
  id("com.android.application") version "7.3.0" apply false
  // ...

  // Add the dependency for the Google services Gradle plugin
  id("com.google.gms.google-services") version "4.4.2" apply false
}

      Groovy 

      plugins {
  id 'com.android.application' version '7.3.0' apply false
  // ...

  // Add the dependency for the Google services Gradle plugin
  id 'com.google.gms.google-services' version '4.4.2' apply false
}

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

      Kotlin 

      plugins {
  id("com.android.application")

  // Add the Google services Gradle plugin
  id("com.google.gms.google-services")
  // ...
}

      Groovy 

      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.kts ou <project>/<app-module>/build.gradle), adicione a dependência da biblioteca do Firebase Cloud Messaging para Android. Recomendamos o uso do Firebase Android BoM para controlar o controle de versões da biblioteca.

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

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.6.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 Firebase Android BoM, seu app sempre vai usar versões compatíveis das bibliotecas do Firebase para Android.

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

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

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

    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:24.1.0")
    implementation("com.google.firebase:firebase-analytics:22.1.2")
}
    Está procurando um módulo de biblioteca específico do Kotlin? A partir de outubro de 2023 (Firebase BoM 32.5.0), os desenvolvedores Kotlin e Java poderão depender do módulo da biblioteca principal. Para mais detalhes, consulte Perguntas frequentes sobre essa iniciativa).

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

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 são dispositivos individuais ou criar grupos de dispositivos, acesse 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():

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

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

Monitorar a geração de tokens

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

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

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

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. Para dispositivos Apple, será necessário aceitar a solicitação de permissão para receber notificações remotas.

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

  3. No console do Firebase, abra a página Mensagens.

  4. Se esta for sua primeira mensagem, selecione Criar primeira campanha.

    1. Selecione Mensagens do Firebase Notificações e clique em Criar.

  5. Se não for sua primeira mensagem, selecione Nova campanha e depois Notificações na guia Campanhas.

  6. Digite o texto da mensagem. Todos os outros campos são opcionais.

  7. Selecione Enviar mensagem de teste no painel à direita.

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

  9. Selecione Testar.

Depois de selecionar Testar, o dispositivo cliente de destino com o app em segundo plano receberá a notificação.

Confira informações sobre a entrega de mensagens ao app 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: