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.

  1. No console do Firebase, clique em Adicionar projeto.

    • Para adicionar recursos do Firebase a um projeto do Google Cloud existente, digite o nome dele ou selecione-o no menu suspenso.

    • Para criar um novo projeto, digite o nome dele. Também é possível editar o ID do projeto exibido abaixo do nome dele.

  2. Se solicitado, leia e aceite os Termos do Firebase.

  3. Clique em Continuar.

  4. (Opcional) Configure o Google Analytics para o projeto e tenha uma experiência ideal quando usar qualquer um destes produtos do Firebase:

    Selecione uma conta do Google Analytics ou crie uma nova.

    Se você criar uma nova conta, selecione seu local do relatório do Analytics e aceite as configurações de compartilhamento de dados e os termos do Google Analytics no projeto.

  5. Clique em Criar projeto ou Adicionar Firebase se você estiver usando um projeto do Google Cloud.

O Firebase provisiona recursos automaticamente para seu projeto. Quando o processo for concluído, vamos direcionar você para a página de visão geral do projeto do Firebase no Console do Firebase.

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.

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

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

      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
      }
      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:

      plugins {
        id("com.android.application")
      
        // Add the Google services Gradle plugin
        id("com.google.gms.google-services")
        // ...
      }
      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.9.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.

    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.2.0")
    }
    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.

    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.kts oi build.gradle no nível do app.
    • Aumente a minSdk 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 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():

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

/**
 * 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)
}
/**
 * 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);
}

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: