O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Configurar um app cliente do Firebase Cloud Messaging no Android

Para criar o app cliente do Firebase Cloud Messaging para Android, use a API FirebaseMessaging e o Android Studio 1.4 ou mais recente com Gradle. Para seguir as instruções desta página, conclua as etapas para adicionar o Firebase ao seu projeto do Android.

Os clientes do FCM exigem que dispositivos com o Android 4.1 ou versões posteriores também tenham o app Google Play Store instalado ou um emulador executando o Android 4.1 com APIs do Google. Não é necessário se limitar à Google Play Store para implementar apps Android.

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.

  • Verifique se o projeto atende a estes requisitos:

    • Está dirigido ao nível 16 da API (Jelly Bean) ou versões posteriores.
    • Usa o Gradle 4.1 ou versões posteriores.
    • Usa o Jetpack (AndroidX), que inclui o cumprimento dos seguintes requisitos de versão:
      • com.android.tools.build:gradle v3.2.1 ou posterior
      • compileSdkVersion 28 ou posterior
  • Configure um dispositivo físico ou use um emulador para executar seu app.
    Os emuladores precisam usar uma imagem de emulador com o Google Play.

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

Se você ainda não tem um projeto Android e quiser testar um produto do Firebase, faça o download de um dos nossos exemplos nos guias de início rápido.

Criar um projeto do Firebase

Antes de adicionar o Firebase ao seu app Android, é preciso criar um projeto do Firebase para então conectá-lo ao seu aplicativo. Visite Noções básicas sobre projetos do Firebase para saber mais.

Registrar o app no Firebase

Depois de criar um projeto do Firebase, é possível adicionar seu app Android a ele.

Consulte Noções básicas sobre projetos do Firebase para ver práticas recomendadas e informações sobre como adicionar apps a um projeto, incluindo como lidar com diversas variantes de compilação.

  1. Acesse o Console do Firebase.

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

    Se você já adicionou um app ao seu projeto do Firebase, clique em Adicionar app para exibir as opções da plataforma.

  3. Digite o nome do pacote do app no campo Nome do pacote do Android.

  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. Para adicionar o arquivo de configuração do Firebase para Android ao app, siga estas etapas:

    1. Clique em Fazer o download do google-services.json para receber o arquivo de configuração do Firebase para Android (google-services.json).

    2. Mova seu arquivo de configuração para o diretório de módulos do seu app.

  2. Para ativar os produtos do Firebase no seu app, adicione o plug-in google-services aos seus arquivos do Gradle.

    1. No arquivo do Gradle (build.gradle) no nível raiz, adicione regras para incluir o plug-in do Serviços do Google para Gradle. Verifique se você tem o repositório Maven do Google também.

      buildscript {
      
        repositories {
          // Check that you have the following line (if not, add it):
          google()  // Google's Maven repository
        }
      
        dependencies {
          // ...
      
          // Add the following line:
          classpath 'com.google.gms:google-services:4.3.4'  // Google Services plugin
        }
      }
      
      allprojects {
        // ...
      
        repositories {
          // Check that you have the following line (if not, add it):
          google()  // Google's Maven repository
          // ...
        }
      }
      
    2. No seu arquivo Gradle do módulo (nível do app) (geralmente app/build.gradle), aplique o plug-in do Serviços do Google para Gradle:

      apply plugin: 'com.android.application'
      // Add the following line:
      apply plugin: 'com.google.gms.google-services'  // Google Services plugin
      
      android {
        // ...
      }
      

Adicionar SDKs do Firebase ao seu app

  1. No arquivo Gradle (geralmente app/build.gradle) do seu módulo (no nível do aplicativo), adicione as dependências dos produtos do Firebase que você quer usar no seu aplicativo.

    É possível adicionar qualquer um dos produtos do Firebase compatíveis ao seu app Android.

    Para uma experiência ideal com o Firebase Cloud Messaging, recomendamos ativar o Google Analytics no seu projeto. Além disso, como parte da configuração do Google Analytics, você precisa adicionar o SDK do Firebase para o Google Analytics ao seu app.

    Analytics ativado

    Java

    dependencies {
      // ...
    
      // Add the dependencies for the Firebase Cloud Messaging and Analytics libraries
      implementation 'com.google.firebase:firebase-messaging:20.3.0'
      implementation 'com.google.firebase:firebase-analytics:17.5.0'
    }
    
    // Getting a "Could not find" error? Make sure that you've added
    // Google's Maven repository to your project-level build.gradle file
    

    Kotlin+KTX

    dependencies {
      // ...
    
      // Add the dependencies for the Firebase Cloud Messaging and Analytics libraries
      implementation 'com.google.firebase:firebase-messaging-ktx:20.3.0'
      implementation 'com.google.firebase:firebase-analytics-ktx:17.5.0'
    }
    
    // Getting a "Could not find" error? Make sure that you've added
    // Google's Maven repository to your project-level build.gradle file
    

    Analytics não ativado

    Java

    dependencies {
      // ...
    
      // Add the dependency for the Firebase Cloud Messaging library
      implementation 'com.google.firebase:firebase-messaging:20.3.0'
    }
    
    // Getting a "Could not find" error? Make sure that you've added
    // Google's Maven repository to your project-level build.gradle file
    

    Kotlin+KTX

    dependencies {
      // ...
    
      // Add the dependency for the Firebase Cloud Messaging library
      implementation 'com.google.firebase:firebase-messaging-ktx:20.3.0'
    }
    
    // Getting a "Could not find" error? Make sure that you've added
    // Google's Maven repository to your project-level build.gradle file
    
  2. Sincronize seu app para garantir que todas as dependências tenham as versões necessárias.

Editar o manifesto do app

Adicione os seguintes itens ao manifesto do app:

  • Um serviço que estende FirebaseMessagingService. Isso é necessário se você quiser processar qualquer mensagem além de simplesmente receber notificações em apps em segundo plano. Para receber notificações em apps em primeiro plano ou payload de dados, enviar mensagens upstream e assim por diante, você precisa 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) Elementos de metadados dentro do componente do aplicativo para definir um ícone e uma cor padrão para notificações. O Android usa esses valores sempre que mensagens recebidas não definem explicitamente o ícone ou a cor do ícone.
  • <!-- 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 (nível da API 26) e posterior, os canais de notificação são aceitos e recomendados. O FCM oferece 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 objeto do 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" />

Acessar o token de registro do dispositivo

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 for dispositivos individuais ou criar grupos de dispositivos, precisará acessar 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():

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 a geração de tokens

O retorno de chamada onNewToken é acionado sempre que um novo token é gerado.

Java

/**
 * Called if InstanceID token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the InstanceID token
 * is initially generated so this is where you would retrieve the token.
 */
@Override
public void onNewToken(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
    // Instance ID token to your app server.
    sendRegistrationToServer(token);
}

Kotlin+KTX

/**
 * Called if InstanceID token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the InstanceID 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
    // Instance ID 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.

Verificar o Google Play Services

Os apps que contam com o 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. Recomenda-se fazer isso em dois lugares: no método onCreate() da atividade principal e no método onResume(). Com a verificação de onCreate(), só é possível utilizar o app após uma verificação bem-sucedida. A verificação de onResume() garante que, se o usuário retornar ao app em execução por outro meio, como pelo botão "Voltar", a verificação ainda será executada.

Se o dispositivo não tiver uma versão compatível do Google Play Services, seu app poderá chamar GoogleApiAvailability.makeGooglePlayServicesAvailable() para permitir que os usuários façam o download do Google Play Services na Play Store.

Impedir a inicialização automática

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

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

Kotlin+KTX

FirebaseMessaging.getInstance().isAutoInitEnabled = true

Depois de definido, esse valor se mantém após as reinicializações do app.

Próximas etapas

Depois que o app cliente estiver configurado, é possível começar a enviar mensagens downstream com o Editor do Notificações. Essa funcionalidade é demonstrada na amostra de início rápido, que você pode fazer o download, executar e avaliar.

Para adicionar outro comportamento mais avançado ao app, você pode declarar um filtro de intent e implementar uma atividade para responder a mensagens recebidas. Para ver mais detalhes, consulte os guias para envio de mensagens de um servidor de app:

É importante lembrar 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.