Envie uma mensagem de teste para um aplicativo 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 compositor de Notificações para um dispositivo de desenvolvimento quando o aplicativo estiver em segundo plano no dispositivo. Esta página lista todas as etapas para fazer isso, desde a configuração até a verificação. Ela pode abranger etapas que você já concluiu se tiver configurado um aplicativo cliente Android para FCM.

Configurar o SDK

Esta seção aborda tarefas que você pode ter concluído se já tiver habilitado outros recursos do Firebase para seu aplicativo.

Antes de você começar

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

  • Certifique-se de que seu projeto atenda a estes requisitos:

    • Segmenta API de nível 19 (KitKat) ou superior
    • Usa Android 4.4 ou superior
    • Usa Jetpack (AndroidX) , que inclui atender a estes requisitos de versão:
      • com.android.tools.build:gradle v7.3.0 ou posterior
      • compileSdkVersion 28 ou posterior
  • Configure um dispositivo físico ou use um emulador para executar seu aplicativo.
    Observe que os SDKs do Firebase que dependem do Google Play Services exigem que o dispositivo ou emulador tenha o Google Play Services instalado.

  • Faça login no Firebase usando sua conta do Google.

Se você ainda não tem um projeto Android e deseja apenas testar um produto Firebase, baixe um de nossos exemplos de início rápido .

Crie um projeto do Firebase

Antes de adicionar o Firebase ao seu aplicativo Android, você precisa criar um projeto do Firebase para se conectar ao seu aplicativo Android. Visite Entenda os projetos do Firebase para saber mais sobre os projetos do Firebase.

Registre seu aplicativo no Firebase

Para usar o Firebase em seu aplicativo Android, você precisa registrar seu aplicativo no projeto do Firebase. Registrar seu aplicativo geralmente é chamado de "adicionar" seu aplicativo ao projeto.

  1. Vá para o console do Firebase .

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

  3. Insira o nome do pacote do seu aplicativo no campo Nome do pacote Android .

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

  5. Clique em Registrar aplicativo .

Adicione um arquivo de configuração do Firebase

  1. Baixe e adicione o arquivo de configuração do Firebase Android ( google-services.json ) ao seu aplicativo:

    1. Clique em Baixar google-services.json para obter seu arquivo de configuração do Firebase Android.

    2. Mova seu arquivo de configuração para o diretório raiz do módulo (nível do aplicativo) do seu aplicativo.

  2. Para tornar os valores em seu arquivo de configuração google-services.json acessíveis aos SDKs do Firebase, você precisa do plug-in Gradle de serviços do Google ( google-services ).

    1. Em seu arquivo Gradle de nível raiz (nível de projeto) ( <project>/build.gradle.kts ou <project>/build.gradle ), adicione o plug-in de 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.1" 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.1' apply false
      }
      
    2. No arquivo Gradle do módulo (nível do aplicativo) (geralmente <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle ), adicione o plug-in de 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'
        // ...
      }
      

Adicione SDKs do Firebase ao seu aplicativo

  1. No arquivo Gradle do módulo (nível do aplicativo) (geralmente <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle ), adicione a dependência para o Firebase Cloud Biblioteca de mensagens para Android. Recomendamos usar o Firebase Android BoM para controlar o controle de versão 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 aplicativo.

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:32.7.2"))
    
        // 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")
    }
    

    Ao usar o Firebase Android BoM , seu aplicativo sempre usará versões compatíveis das bibliotecas do Firebase Android.

    (Alternativa) Adicionar dependências da biblioteca Firebase sem usar o BoM

    Se você optar por não usar o Firebase BoM, deverá especificar cada versão da biblioteca do Firebase em sua linha de dependência.

    Observe que se você usa várias bibliotecas do Firebase no seu aplicativo, é altamente recomendável usar a BoM para gerenciar as versões da biblioteca, o que garante que todas as versões sejam compatíveis.

    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.4.1")
        implementation("com.google.firebase:firebase-analytics:21.5.1")
    }
    
    Procurando um módulo de biblioteca específico para Kotlin? A partir de outubro de 2023 (Firebase BoM 32.5.0) , tanto os desenvolvedores Kotlin quanto os Java podem depender do módulo da biblioteca principal (para obter detalhes, consulte o FAQ sobre esta iniciativa ).

  2. Sincronize seu projeto Android com arquivos Gradle.

Acesse o token de registro

Para enviar uma mensagem para um dispositivo específico, você precisa saber o token de registro desse dispositivo. Como você precisará inserir o token em um campo no console de Notificações para concluir este tutorial, copie o token ou armazene-o com segurança após recuperá-lo.

Na inicialização do seu aplicativo, o SDK do FCM gera um token de registro para a instância do aplicativo cliente. Se quiser segmentar dispositivos únicos ou criar grupos de dispositivos, você precisará acessar esse token estendendo FirebaseMessagingService e substituindo onNewToken .

Esta seção descreve como recuperar o token e como monitorar alterações no token. Como o token pode ser alternado após a inicialização, é altamente recomendável recuperar o token de registro atualizado mais recente.

O token de registro pode mudar quando:

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

Recuperar o token de registro atual

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

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

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

Depois de obter o token, você pode enviá-lo ao servidor do aplicativo e armazená-lo usando o método de sua preferência.

Envie uma mensagem de notificação de teste

  1. Instale e execute o aplicativo no dispositivo de destino. Em dispositivos Apple, você precisará aceitar a solicitação de permissão para receber notificações remotas.

  2. Certifique-se de que o aplicativo esteja em segundo plano no dispositivo.

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

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

    1. Selecione Mensagens de notificação do Firebase e selecione Criar .
  5. Caso contrário, na guia Campanhas , selecione Nova campanha e depois Notificações .

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

  7. Selecione Enviar mensagem de teste no painel direito.

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

  9. Selecione Teste .

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

Para obter informações sobre a entrega de mensagens no seu aplicativo, consulte o painel de relatórios do FCM , que registra o número de mensagens enviadas e abertas em dispositivos Apple e Android, juntamente com dados de "impressões" (notificações vistas pelos usuários) para aplicativos Android.

Próximos passos

Envie mensagens para aplicativos em primeiro plano

Depois de enviar mensagens de notificação com sucesso enquanto seu aplicativo está em segundo plano, consulte Receber mensagens em um aplicativo Android para começar a enviar para aplicativos 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 aplicativo, consulte: