Configure um aplicativo cliente Firebase Cloud Messaging no Android

Os clientes FCM exigem dispositivos com Android 4.4 ou superior que também tenham o aplicativo Google Play Store instalado ou um emulador com 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 aborda tarefas que você pode ter concluído se já tiver habilitado outros recursos do Firebase para seu aplicativo. Adicione o Firebase ao seu projeto Android , caso ainda não o tenha feito.

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 lidar com qualquer mensagem além de receber notificações em aplicativos em segundo plano. Para receber notificações em aplicativos em primeiro plano, para receber carga útil de dados, para 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) Dentro do 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 versões posteriores, os canais de notificação são suportados 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 como o ID do 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" />

Solicite 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 mostrar notificações até que o usuário conceda essa permissão.

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

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

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

Geralmente, você deve exibir uma UI explicando ao usuário os recursos que serão habilitados se ele conceder permissões para o aplicativo postar notificações. Esta IU deve fornecer ao usuário opções para concordar ou negar, como botões OK e Não, obrigado . Se o usuário selecionar OK , solicite diretamente a permissão. 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 apps 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, existem advertências importantes em relação ao momento da criação do canal e às solicitações de permissão:

  • Se o 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é o próximo 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 fortemente 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 deverá 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 para 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 usa mensagens de notificação (seja por meio de notificações do FCM, de outro SDK ou postadas diretamente pelo seu aplicativo) e você não deseja que seu aplicativo inclua a permissão, você pode removê-lo usando o marcador remove da fusão de manifesto . Lembre-se de que a remoção dessa 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 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.

Verifique os serviços do Google Play

Os aplicativos que dependem do SDK do 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 locais: 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. A verificação 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 na Play Store.

Impedir a inicialização automática

Quando um token de registro do FCM é gerado, a biblioteca faz upload do identificador e dos dados de configuração para o Firebase. Se você preferir evitar a geração automática de tokens, desative a coleta do Analytics e a inicialização automática do FCM (você deve desativar ambas) 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:

Kotlin+KTX

Firebase.messaging.isAutoInitEnabled = true

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(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, uma vez definidos.

Próximos passos

Após a configuração do aplicativo cliente, você estará pronto para começar a enviar mensagens downstream com o Notifications Composer . 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 de servidor (HTTP ou XMPP) ou de uma implementação do Admin SDK .