Configurar um app cliente do Firebase Cloud Messaging com o Unity

Para criar o seu aplicativo cliente multiplataforma do Firebase Cloud Messaging com o Unity, use a API Firebase Cloud Messaging. O SDK do Unity funciona com Android e Apple, sendo necessárias configurações a mais em cada plataforma.

Antes de começar

Pré-requisitos

• Instale o Unity 2018.4 ou uma versão mais recente. As versões anteriores também podem ser compatíveis, mas não terão um amplo suporte. A compatibilidade com o Unity 2018.4 foi descontinuada e não terá mais suporte após o lançamento da próxima versão principal.

• Instale os seguintes itens (somente para iOS):

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

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

  • Para iOS: voltado a iOS 10 ou versões mais recentes

  • Para Android: voltado ao nível 19 da API (KitKat) ou mais recente

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

  • Para iOS: configure um dispositivo iOS físico para executar seu app e conclua as tarefas a seguir:

    • Consiga 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.

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

Se você ainda não tem um projeto do Unity e quer testar um produto do Firebase, faça o download de uma de nossas amostras de guia de início rápido.

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 (plat_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 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.

   Onde fica o ID do projeto do Unity?

   Abra o projeto do Unity no ambiente de desenvolvimento integrado do Unity e navegue até a seção de configurações de cada plataforma:

   • Para iOS: acesse Build Settings > iOS.

   • Para Android: acesse Android > Player Settings > Other Settings.

   O ID do seu projeto do Unity é o valor em Bundle Identifier (ID de exemplo: com.yourcompany.yourproject).

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.

   O que é preciso saber sobre esse arquivo de configuração?

   • O arquivo de configuração do Firebase contém identificadores exclusivos, mas não secretos, para seu projeto. Para saber mais sobre esse arquivo de configuração, acesse Noções básicas sobre projetos do Firebase.

   • É possível fazer o download do arquivo de configuração do Firebase novamente a qualquer momento.

   • Verifique se o nome do arquivo de configuração não está anexado com caracteres adicionais, como (2).

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 um local prático.

   • É 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 da 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 seu app.

   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 pacote do Firebase para o Google Analytics ao seu aplicativo.

   Analytics ativado

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

   Analytics não ativado

   Adicione o pacote para o 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 no Android requer a plataforma Google Play Services, que precisa estar atualizada antes que o SDK possa ser usado.

Adicione o seguinte código no início do seu 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.

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(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 Unity é registrado e configurado para usar o Firebase.

Etapa 7: adicionar o framework de notificações do usuário

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 exibida, role até UserNotifications.framework e clique nessa entrada. Depois, clique em Add.

Etapa 8: 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, o Firebase Cloud Messaging vem em um pacote com uma atividade de ponto de entrada personalizado que substitui o UnityPlayerActivity padrão. Se você não estiver usando um ponto de entrada personalizado, essa substituição acontecerá automaticamente e você não precisa 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 Firebase Cloud Messaging no Android acompanha 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 a UnityPlayerActivity padrão não processa transições de ciclo de vida onStop e onRestart de atividades nem implementa onNewIntent, que é necessária 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 gerencia 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 seguintes snippets 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 aplicativo não está em execução e um usuário toca em uma notificação, por padrão, a mensagem não é encaminhada por meio dos callbacks incorporados do FCM. Nesse caso, os payloads das mensagens são recebidos com uma Intent usada para iniciar o aplicativo.

O conteúdo do campo de notificação das mensagens recebidas enquanto o app está em segundo plano é usado para preencher a notificação da bandeja do sistema. No entanto, esse conteúdo não será comunicado ao FCM. Isso significa que FirebaseMessage.Notification será nulo.

Em resumo:

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:

<?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>

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.

Como processar mensagens com links diretos no Android

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. 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, você está 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:

• Enviar mensagens de tópicos
• Enviar a grupos de dispositivos
• Enviar mensagens upstream

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