Acompanhe tudo o que foi anunciado no Firebase Summit e saiba como usar o Firebase para acelerar o desenvolvimento de apps e executá-los com confiança. Saiba mais

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 aborda 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 manipulação 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) 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 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 em 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 em execução no Android 13 ou superior que usam notificações do FCM.

Por padrão, o FCM SDK (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 IU explicando ao usuário os recursos que serão ativados se ele conceder 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 solicita automaticamente a permissão do 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 sobre o 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é o próximo hora 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 Android 13+ para aproveitar 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 FCM SDK inclui a permissão POST_NOTIFICATIONS . Se seu aplicativo não usa mensagens de notificação (seja por meio de notificações do FCM, por meio de outro SDK ou postadas diretamente por seu aplicativo) e você não deseja que seu aplicativo inclua a permissão, você pode removê-lo usando o marcador de 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 inicial de seu aplicativo, o FCM SDK gera um token de registro para a instância do aplicativo cliente. Se você deseja 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 alterações no token. Como o token pode ser girado 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.

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

Monitorar geração de token

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 seu servidor de aplicativos e armazená-lo usando seu método preferido.

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. É recomendável fazer isso em dois locais: no método onCreate() da atividade principal e no método onResume() da atividade principal. A verificação em onCreate() garante que o aplicativo não possa ser usado sem uma verificação bem-sucedida. A verificação em onResume() garante que, se o usuário retornar ao aplicativo em execução por algum outro meio, como por meio do botão Voltar, a verificação ainda será executada.

Se o dispositivo não tiver uma versão compatível dos serviços do Google Play, seu aplicativo poderá chamar GoogleApiAvailability.makeGooglePlayServicesAvailable() para permitir que os usuários façam o download dos serviços do Google Play na 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 impedir 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:

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 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 intenção e implementar uma atividade para responder às mensagens recebidas. Para obter detalhes, consulte os guias para envio de 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 uma implementação do Admin SDK .