Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

Configurar um aplicativo cliente Firebase Cloud Messaging no Android

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Os clientes FCM exigem dispositivos com Android 4.4 ou superior que também tenham o aplicativo Google Play Store instalado ou um emulador executando Android 4.4 com APIs do Google. Observe que você não está limitado a implantar seus aplicativos Android por meio da Google Play Store.

Configurar o SDK

Esta seção abrange as tarefas que você pode ter concluído se já tiver ativado outros recursos do Firebase para seu aplicativo. Se ainda não o fez, adicione o Firebase ao seu projeto Android

Edite o manifesto do seu aplicativo

Adicione o seguinte ao manifesto do seu aplicativo:

  • Um serviço que estende FirebaseMessagingService . Isso é necessário se você quiser fazer qualquer tratamento de mensagens além de receber notificações em aplicativos em segundo plano. Para receber notificações em aplicativos em primeiro plano, receber carga útil de dados, enviar mensagens upstream e assim por diante, você deve estender esse serviço.
  • <service
        android:name=".java.MyFirebaseMessagingService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
  • (Opcional) No componente do aplicativo, elementos de metadados para definir um ícone e uma cor de notificação padrão. O Android usa esses valores sempre que as mensagens recebidas não definem explicitamente o ícone ou a cor.
  • <!-- Set custom default icon. This is used when no icon is set for incoming notification messages.
         See README(https://goo.gl/l4GJaQ) for more. -->
    <meta-data
        android:name="com.google.firebase.messaging.default_notification_icon"
        android:resource="@drawable/ic_stat_ic_notification" />
    <!-- Set color used with incoming notification messages. This is used when no color is set for the incoming
         notification message. See README(https://goo.gl/6BKBk7) for more. -->
    <meta-data
        android:name="com.google.firebase.messaging.default_notification_color"
        android:resource="@color/colorAccent" />
  • (Opcional) A partir do Android 8.0 (API de nível 26) e superior, os canais de notificação são compatíveis e recomendados. O FCM fornece um canal de notificação padrão com configurações básicas. Se você preferir criar e usar seu próprio canal padrão, defina default_notification_channel_id para o ID de seu objeto de canal de notificação, conforme mostrado; O FCM usará esse valor sempre que as mensagens recebidas não definirem explicitamente um canal de notificação. Para saber mais, consulte Gerenciar canais de notificação .
  • <meta-data
        android:name="com.google.firebase.messaging.default_notification_channel_id"
        android:value="@string/default_notification_channel_id" />

Solicitar permissão de notificação de tempo de execução no Android 13+

O Android 13 apresenta uma nova permissão de tempo de execução para mostrar notificações. Isso afeta todos os aplicativos executados no Android 13 ou superior que usam notificações do FCM.

Por padrão, o SDK do FCM (versão 23.0.6 ou superior) inclui a permissão POST_NOTIFICATIONS definida no manifesto. No entanto, seu aplicativo também precisará solicitar a versão de tempo de execução dessa permissão por meio da constante android.permission.POST_NOTIFICATIONS . Seu aplicativo não terá permissão para exibir notificações até que o usuário conceda essa permissão.

Para solicitar a nova permissão de tempo de execução:

Java

// Declare the launcher at the top of your Activity/Fragment:
private final ActivityResultLauncher<String> requestPermissionLauncher =
        registerForActivityResult(new ActivityResultContracts.RequestPermission(), isGranted -> {
            if (isGranted) {
                // FCM SDK (and your app) can post notifications.
            } else {
                // TODO: Inform user that that your app will not show notifications.
            }
        });

private void askNotificationPermission() {
    // This is only necessary for API level >= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
                PackageManager.PERMISSION_GRANTED) {
            // FCM SDK (and your app) can post notifications.
        } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
            // TODO: display an educational UI explaining to the user the features that will be enabled
            //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
            //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
            //       If the user selects "No thanks," allow the user to continue without notifications.
        } else {
            // Directly ask for the permission
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS);
        }
    }
}

Kotlin+KTX

// Declare the launcher at the top of your Activity/Fragment:
private val requestPermissionLauncher = registerForActivityResult(
    ActivityResultContracts.RequestPermission()
) { isGranted: Boolean ->
    if (isGranted) {
        // FCM SDK (and your app) can post notifications.
    } else {
        // TODO: Inform user that that your app will not show notifications.
    }
}

private fun askNotificationPermission() {
    // This is only necessary for API level >= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
            PackageManager.PERMISSION_GRANTED
        ) {
            // FCM SDK (and your app) can post notifications.
        } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
            // TODO: display an educational UI explaining to the user the features that will be enabled
            //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
            //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
            //       If the user selects "No thanks," allow the user to continue without notifications.
        } else {
            // Directly ask for the permission
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
        }
    }
}

Geralmente, você deve exibir uma interface do usuário explicando ao usuário os recursos que serão ativados se eles concederem permissões para o aplicativo postar notificações. Essa interface do usuário deve fornecer ao usuário opções para concordar ou negar, como os botões OK e Não, obrigado . Se o usuário selecionar OK , solicite a permissão diretamente. Se o usuário selecionar Não, obrigado , permita que o usuário continue sem notificações.

Consulte Permissão de tempo de execução de notificação para obter mais práticas recomendadas sobre quando seu aplicativo deve solicitar a permissão POST_NOTIFICATIONS do usuário.

Permissões de notificação para aplicativos direcionados ao Android 12L (API de nível 32) ou inferior

O Android pede permissão automaticamente ao usuário na primeira vez que seu aplicativo cria um canal de notificação, desde que o aplicativo esteja em primeiro plano. No entanto, há ressalvas importantes em relação ao tempo de criação do canal e solicitações de permissão:

  • Se seu aplicativo criar seu primeiro canal de notificação quando estiver sendo executado em segundo plano (o que o SDK do FCM faz ao receber uma notificação do FCM), o Android não permitirá que a notificação seja exibida e não solicitará ao usuário a permissão de notificação até a próxima momento em que seu aplicativo é aberto. Isso significa que todas as notificações recebidas antes de seu aplicativo ser aberto e o usuário aceitar a permissão serão perdidas .
  • Recomendamos que você atualize seu aplicativo para o Android 13+ e aproveite as APIs da plataforma para solicitar permissão. Se isso não for possível, seu aplicativo deve criar canais de notificação antes de enviar qualquer notificação ao aplicativo para acionar a caixa de diálogo de permissão de notificação e garantir que nenhuma notificação seja perdida. Consulte as práticas recomendadas de permissão de notificação para obter mais informações.

Opcional: remova a permissão POST_NOTIFICATIONS

Por padrão, o SDK do FCM inclui a permissão POST_NOTIFICATIONS . Se seu aplicativo não usar mensagens de notificação (seja por meio de notificações do FCM, por meio de outro SDK ou postado diretamente pelo seu aplicativo) e você não quiser que seu aplicativo inclua a permissão, poderá removê-lo usando o marcador de remove da fusão do manifesto . Lembre-se de que remover essa permissão impede a exibição de todas as notificações, não apenas das notificações do FCM. Adicione o seguinte ao arquivo de manifesto do seu aplicativo:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" tools:node="remove"/>

Acesse o token de registro do dispositivo

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

Esta seção descreve como recuperar o token e como monitorar as alterações no token. Como o token pode ser alternado após a inicialização inicial, é 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 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 geração de token

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

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

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

Verifique os serviços do Google Play

Os aplicativos que dependem do SDK do Google Play Services devem sempre verificar se há um APK do Google Play Services compatível no dispositivo antes de acessar os recursos do Google Play Services. Recomenda-se fazer isso em dois lugares: no método onCreate() da atividade principal e em seu método onResume() . O check-in onCreate() garante que o aplicativo não possa ser usado sem uma verificação bem-sucedida. O check-in onResume() garante que, se o usuário retornar ao aplicativo em execução por algum outro meio, como o botão Voltar, a verificação ainda será realizada.

Se o dispositivo não tiver uma versão compatível do Google Play Services, seu aplicativo poderá chamar GoogleApiAvailability.makeGooglePlayServicesAvailable() para permitir que os usuários baixem o Google Play Services da Play Store.

Impedir a inicialização automática

Quando um token de registro do FCM é gerado, a biblioteca carrega o identificador e os dados de configuração para o Firebase. Se você preferir evitar a geração automática de token, desative a coleta do Analytics e a inicialização automática do FCM (você deve desativar ambos) adicionando estes valores de metadados ao seu AndroidManifest.xml :

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />

Para reativar a inicialização automática do FCM, faça uma chamada de tempo de execução:

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

Kotlin+KTX

Firebase.messaging.isAutoInitEnabled = true

Para reativar a coleta do Analytics, chame o método setAnalyticsCollectionEnabled() da classe FirebaseAnalytics . Por exemplo:

setAnalyticsCollectionEnabled(true);

Esses valores persistem nas reinicializações do aplicativo depois de definidos.

Próximos passos

Depois que o aplicativo cliente estiver configurado, você estará pronto para começar a enviar mensagens downstream com o compositor de notificações . Essa funcionalidade é demonstrada no exemplo de início rápido , que você pode baixar, executar e revisar.

Para adicionar outro comportamento mais avançado ao seu aplicativo, você pode declarar um filtro de intent e implementar uma atividade para responder às mensagens recebidas. Para obter detalhes, consulte os guias para enviar mensagens de um servidor de aplicativos:

Lembre-se de que, para aproveitar esses recursos, você precisará de uma implementação de servidor e dos protocolos do servidor (HTTP ou XMPP) ou de uma implementação do SDK Admin .