Configurar um app cliente do Firebase Cloud Messaging com o Unity

Para criar um app cliente multiplataforma do Firebase Cloud Messaging com o Unity, use a API Firebase Cloud Messaging. O SDK do Unity funciona no Android e Apple, mas algumas configurações adicionais são necessárias para cada plataforma.

Antes de começar

Pré-requisitos

  • Instale o Unity 2021 LTS ou uma versão mais recente. O suporte ao Unity 2020 foi descontinuado e não será mais oferecido após o lançamento da próxima versão principal. As versões anteriores também podem ser compatíveis, mas não terão um amplo suporte.

  • (Somente em plataformas da Apple) Instale o seguinte:

    • Xcode 13.3.1 ou versões mais recentes
    • CocoaPods 1.12.0 ou versões mais recentes

  • Verifique se o projeto do Unity atende aos requisitos a seguir:

    • Para iOS: voltado ao iOS 13 ou versões mais recentes
    • Para tvOS: voltado ao tvOS 13 ou versões mais recentes
    • Para Android: segmenta o nível 21 da API (Lollipop) ou mais recente.

  • Configure um dispositivo ou use um emulador para executar seu projeto do Unity.

    • Para iOS ou tvOS: configure um dispositivo físico para executar seu app e conclua estas tarefas:

      • Conseguir uma chave de autenticação de notificação push da Apple para sua conta do Apple Developer.
      • Ative as notificações push no XCode em App > Capabilities.

    • Para Android: os emuladores precisam usar uma imagem de emulador no Google Play.

Se você ainda não tem um projeto do Unity e quer testar um produto do Firebase, faça o download de uma das nossas amostras introdutórias.

Etapa 1: criar um projeto do Firebase

Antes de adicionar o Firebase ao seu projeto Unity, é preciso criar um projeto do Firebase para ser conectado ao seu projeto Unity. Consulte Noções básicas sobre projetos do Firebase para mais informações.

Etapa 2: registrar seu app com o Firebase

É possível registrar um ou mais apps ou jogos para conectar ao seu projeto do Firebase.

  1. Acesse o Console do Firebase,

  2. No centro da página de visão geral do projeto, clique no ícone do Unity () 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. Selecione qual destino de build do seu projeto do Unity você quer registrar ou opte por registrar os dois destinos agora.

  4. Digite os IDs específicos da plataforma do seu projeto do Unity.

    • Para iOS: insira o ID do iOS do seu projeto do Unity no campo ID do pacote do iOS.

    • Para Android: insira o ID do Android do seu projeto do Unity no campo Nome do pacote Android.
      Os termos nome do pacote e ID do aplicativo geralmente são usados de maneira intercambiável.

  5. (Opcional) Digite os apelidos específicos da plataforma do seu projeto do Unity.
    Esses apelidos são identificadores de conveniência internos e só são visíveis para você no Console do Firebase.

  6. Clique em Registrar app.

Etapa 3: adicionar arquivos de configuração do Firebase

  1. Receba seus arquivos de configuração do Firebase específicos da plataforma no fluxo de trabalho de configuração do Console do Firebase.

    • Para iOS: clique em Download GoogleService-Info.plist.

    • Para Android: clique em Download google-services.json.

  2. Abra a janela Projeto do seu projeto do Unity e mova seus arquivos de configuração para a pasta Assets.

  3. De volta ao fluxo de trabalho de configuração no Console do Firebase, clique em Avançar.

Etapa 4: adicionar SDKs do Firebase para Unity

  1. No console do Firebase, clique em Fazer o download do SDK do Firebase para Unity e descompacte o SDK em algum lugar conveniente.

    • É possível fazer o download do SDK do Firebase para Unity novamente a qualquer momento.

    • O SDK do Firebase para Unity não é específico de nenhuma plataforma.

  2. No seu projeto aberto do Unity, acesse Assets > Import Package > Custom Package.

  3. No SDK descompactado, selecione os produtos compatíveis do Firebase que você quer usar no aplicativo.

    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 Analytics, você precisa adicionar o pacote do Firebase para Analytics ao seu app.

    Analytics ativado

    • Adicione o pacote do Firebase para Google Analytics: FirebaseAnalytics.unitypackage
    • Adicione o pacote para Firebase Cloud Messaging: FirebaseMessaging.unitypackage

    Analytics não ativado

    Adicione o pacote para Firebase Cloud Messaging: FirebaseMessaging.unitypackage

  4. Na janela Import Unity Package, clique em Import.

  5. De volta ao fluxo de trabalho de configuração no Console do Firebase, clique em Avançar.

Etapa 5: confirmar os requisitos da versão do Google Play Services

O SDK do Firebase para Unity para Android requer Google Play services, que precisa estar atualizado antes que o SDK possa ser usado.

Adicione a instrução using e o código de inicialização abaixo no início do aplicativo. É possível verificar e, como opção, atualizar o Google Play services para a versão exigida pelo SDK do Firebase para Unity antes de chamar outros métodos no SDK.

using Firebase.Extensions;

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWithOnMainThread(task => {
  var dependencyStatus = task.Result;
  if (dependencyStatus == Firebase.DependencyStatus.Available) {
    // Create and hold a reference to your FirebaseApp,
    // where app is a Firebase.FirebaseApp property of your application class.
       app = Firebase.FirebaseApp.DefaultInstance;

    // Set a flag here to indicate whether Firebase is ready to use by your app.
  } else {
    UnityEngine.Debug.LogError(System.String.Format(
      "Could not resolve all Firebase dependencies: {0}", dependencyStatus));
    // Firebase Unity SDK is not safe to use here.
  }
});

Seu projeto do Unity está registrado e configurado para usar o Firebase.

Faça upload da chave de autenticação de APNs para o suporte da Apple

Faça upload da chave de autenticação de APNs para o Firebase. Se você ainda não tiver uma chave de autenticação de APNs, crie uma no Apple Developer Member Center.

  1. No seu projeto no console do Firebase, selecione o ícone de engrenagem, clique em Configurações do projeto e selecione a guia Cloud Messaging.

  2. Acesse a Configuração do app iOS. Em Chave de autenticação de APNs, clique no botão Fazer upload.

  3. Navegue até o local onde você salvou a chave, selecione-a e clique em Abrir. Adicione o ID da chave disponível no Apple Developer Member Center e clique em Fazer upload.

Ativar as notificações push nas plataformas Apple

Etapa 1: adicionar o framework de notificações dos usuários

  1. Clique no projeto no Xcode e selecione a guia General na Editor area.

  2. Role para baixo até Linked Frameworks and Libraries e clique no botão com o símbolo + para adicionar um framework.

  3. Na janela mostrada, role até UserNotifications.framework, clique nessa entrada e depois selecione Add.

Etapa 2: ativar as notificações push

  1. Clique no projeto no Xcode e selecione a guia Capabilities na Editor area.

  2. Mude Push Notifications para On.

  3. Role para baixo até Background Modes e mude para On.

  4. Marque a caixa Remote notifications em Background Modes.

Inicializar o Firebase Cloud Messaging

A biblioteca do Firebase Cloud Messaging é inicializada quando gerenciadores são adicionados aos eventos TokenReceived ou MessageReceived.

Na inicialização, um token de registro é solicitado para a instância do app cliente. O app recebe o token com o evento OnTokenReceived, que precisa ser armazenado em cache para uso posterior. Esse token será necessário se você quiser usar esse dispositivo específico para mensagens.

Além disso, você precisará se registrar para o evento OnMessageReceived se quiser receber mensagens.

Toda a configuração tem esta aparência:

public void Start() {
  Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
  Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
}

public void OnTokenReceived(object sender, Firebase.Messaging.TokenReceivedEventArgs token) {
  UnityEngine.Debug.Log("Received Registration Token: " + token.Token);
}

public void OnMessageReceived(object sender, Firebase.Messaging.MessageReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received a new message from: " + e.Message.From);
}

Como configurar uma atividade de ponto de entrada do Android

No Android, a Firebase Cloud Messaging vem em um pacote com uma atividade de ponto de entrada personalizada que substitui a UnityPlayerActivity padrão. Se você não estiver usando um ponto de entrada personalizado, essa substituição vai acontecer automaticamente, e você não precisará fazer mais nada. Os apps que não usam a atividade de ponto de entrada padrão ou que fornecem os próprios Assets/Plugins/AndroidManifest.xml precisarão de uma configuração extra.

O plug-in do Unity para o Firebase Cloud Messaging no Android vem com dois arquivos adicionais:

  • O Assets/Plugins/Android/libmessaging_unity_player_activity.jar contém uma atividade chamada MessagingUnityPlayerActivity que substitui a UnityPlayerActivity padrão.
  • O Assets/Plugins/Android/AndroidManifest.xml instrui o app a usar MessagingUnityPlayerActivity como o ponto de entrada para o app.

Esses arquivos são fornecidos porque o UnityPlayerActivity padrão não processa transições de ciclo de vida da atividade onStop e onRestart nem implementa o onNewIntent, que é necessário para que o Firebase Cloud Messaging processe corretamente as mensagens recebidas.

Como configurar uma atividade de ponto de entrada personalizada

Se o app não usa a UnityPlayerActivity padrão, remova o AndroidManifest.xml fornecido e verifique se a atividade personalizada está gerenciando corretamente todas as transições do ciclo de vida de atividades do Android. Veja abaixo um exemplo desse procedimento. Se sua atividade personalizada estender a UnityPlayerActivity, estenda a com.google.firebase.MessagingUnityPlayerActivity, que implementa todos os métodos necessários.

Se você estiver usando uma atividade personalizada e não estender a com.google.firebase.MessagingUnityPlayerActivity, será necessário incluir os snippets a seguir na sua atividade.

/**
 * Workaround for when a message is sent containing both a Data and Notification payload.
 *
 * When the app is in the background, if a message with both a data and notification payload is
 * received the data payload is stored on the Intent passed to onNewIntent. By default, that
 * intent does not get set as the Intent that started the app, so when the app comes back online
 * it doesn't see a new FCM message to respond to. As a workaround, we override onNewIntent so
 * that it sends the intent to the MessageForwardingService which forwards the message to the
 * FirebaseMessagingService which in turn sends the message to the application.
 */
@Override
protected void onNewIntent(Intent intent) {
  Intent message = new Intent(this, MessageForwardingService.class);
  message.setAction(MessageForwardingService.ACTION_REMOTE_INTENT);
  message.putExtras(intent);
  message.setData(intent.getData());
  // For older versions of Firebase C++ SDK (< 7.1.0), use `startService`.
  // startService(message);
  MessageForwardingService.enqueueWork(this, message);
}

/**
 * Dispose of the mUnityPlayer when restarting the app.
 *
 * This ensures that when the app starts up again it does not start with stale data.
 */
@Override
protected void onCreate(Bundle savedInstanceState) {
  if (mUnityPlayer != null) {
    mUnityPlayer.quit();
    mUnityPlayer = null;
  }
  super.onCreate(savedInstanceState);
}

As novas versões do SDK do Firebase para C++ (7.1.0 em diante) usam JobIntentService, que requer modificações adicionais no arquivo AndroidManifest.xml.

<service android:name="com.google.firebase.messaging.MessageForwardingService"
     android:permission="android.permission.BIND_JOB_SERVICE"
     android:exported="false" >
</service>

Observação sobre entrega de mensagens no Android

Quando o app não está em execução e um usuário toca em uma notificação, por padrão, a mensagem não é encaminhada usando as callbacks incorporadas do FCM. Nesse caso, os payloads das mensagens são recebidos por meio de um Intent usado para iniciar o aplicativo.

As mensagens recebidas enquanto o aplicativo está em segundo plano têm o conteúdo do campo de notificação usado para preencher a notificação da bandeja do sistema, mas esse conteúdo não será comunicado ao FCM. Ou seja, FirebaseMessage.Notification será nulo.

Em resumo:

Estado do app Notificação Dados Ambos
Primeiro plano Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
Experiência Bandeja do sistema Firebase.Messaging.FirebaseMessaging.MessageReceived Notificação: bandeja do sistema
Dados: nos extras da intent.

Impedir a inicialização automática

O FCM gera um token de registro para segmentação por dispositivo. Quando um token é gerado, a biblioteca faz upload dos dados de configuração e do identificador para o Firebase. Se você quiser receber uma confirmação antes de usar o token, é possível impedir a geração dele desativando o FCM (e o Analytics no Android). Para isso, adicione um valor de metadados ao Info.plist, e não ao GoogleService-Info.plist, na Apple ou ao AndroidManifest.xml no Android:

Android

<?xml version="1.0" encoding="utf-8"?>
<application>
  <meta-data android:name="firebase_messaging_auto_init_enabled"
             android:value="false" />
  <meta-data android:name="firebase_analytics_collection_enabled"
             android:value="false" />
</application>

Swift

FirebaseMessagingAutoInitEnabled = NO

Para reativar o FCM, é possível fazer uma chamada de ambiente de execução:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Depois de definido, esse valor persiste às reinicializações do app.

O FCM permite que sejam enviadas mensagens com um link direto para seu aplicativo. Para receber mensagens que contenham um link direto, é necessário adicionar um novo filtro de intent à atividade que processa links diretos para seu aplicativo. O filtro de intent precisa capturar links diretos do seu domínio. Se as suas mensagens não contiverem um link direto, essa configuração não será necessária. No AndroidManifest.xml:

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="http"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="https"/>
</intent-filter>

Também é possível especificar um caractere curinga para deixar o filtro de intent mais flexível. Por exemplo:

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="*.example.com" android:scheme="http"/>
  <data android:host="*.example.com" android:scheme="https"/>
</intent-filter>

Quando os usuários tocam em uma notificação que contém um link para o esquema e o host especificados por você, seu aplicativo iniciará a atividade com esse filtro de intent para processar o link.

Próximas etapas

Depois de configurar o app cliente, tudo vai estar pronto para enviar mensagens de tópico e downstream com o Firebase. Para saber mais, consulte a amostra introdutória que demonstra essa funcionalidade.

Para adicionar outros comportamentos mais avançados ao app, consulte os guias para envio de mensagens de um servidor de apps:

Saiba que você precisará de uma implementação de servidor para usar esses recursos.