Configure um aplicativo cliente do Firebase Cloud Messaging com Unity

Para escrever seu aplicativo cliente Firebase Cloud Messaging multiplataforma com Unity, use a API Firebase Cloud Messaging . O Unity SDK funciona tanto para Android quanto para Apple, com algumas configurações adicionais necessárias para cada plataforma.

Antes de você começar

Pré-requisitos

  • Instale o Unity 2019.1 ou posterior. Versões anteriores também podem ser compatíveis, mas não terão suporte ativo. O suporte para Unity 2019.1 é considerado obsoleto e não terá mais suporte ativo após a próxima versão principal.

  • (Somente plataformas Apple) Instale o seguinte:

    • Xcode 13.3.1 ou superior
    • CocoaPods 1.12.0 ou superior

  • Certifique-se de que seu projeto Unity atenda a estes requisitos:

    • Para iOS – direcionado ao iOS 11 ou superior
    • Para tvOS – direcionado ao tvOS 12 ou superior
    • Para Android – direcionado ao nível 19 da API (KitKat) ou superior

  • 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 aplicativo e conclua estas tarefas:

      • Obtenha uma chave de autenticação de notificação push da Apple para sua conta de desenvolvedor Apple .
      • Habilite notificações push no XCode em App > Capabilities .

    • Para Android – os emuladores devem usar uma imagem de emulador com o Google Play.

Se você ainda não tem um projeto Unity e deseja apenas testar um produto Firebase, faça download de um de nossos exemplos de início rápido .

Etapa 1: crie um projeto Firebase

Antes de adicionar o Firebase ao seu projeto do Unity, você precisa criar um projeto do Firebase para se conectar ao seu projeto do Unity. Visite Entenda os projetos do Firebase para saber mais sobre os projetos do Firebase.

Etapa 2: registre seu aplicativo no Firebase

Você pode registrar um ou mais aplicativos ou jogos para conectar ao seu projeto do Firebase.

  1. Vá para o console do Firebase .

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

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

  3. Selecione qual destino de compilação do seu projeto Unity você gostaria de registrar ou você pode até optar por registrar ambos os alvos agora ao mesmo tempo.

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

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

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

  5. (Opcional) Insira os apelidos específicos da plataforma do seu projeto Unity.
    Esses apelidos são identificadores internos e convenientes e só ficam visíveis para você no console do Firebase.

  6. Clique em Registrar aplicativo .

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

  1. Obtenha 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 Baixar GoogleService-Info.plist .

    • Para Android – clique em Baixar google-services.json .

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

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

Etapa 4: adicionar SDKs do Firebase Unity

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

    • Você pode fazer download do SDK do Firebase Unity novamente a qualquer momento.

    • O SDK do Firebase Unity não é específico da plataforma.

  2. Em seu projeto aberto do Unity, navegue até Assets > Import Package > Custom Package .

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

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

    Análise ativada

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

    Análise não ativada

    Adicione o pacote para Firebase Cloud Messaging: FirebaseMessaging.unitypackage

  4. Na janela Importar pacote do Unity , clique em Importar .

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

Etapa 5: confirme os requisitos de versão do Google Play Services

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

Adicione a seguinte instrução using e o código de inicialização no início do seu aplicativo. Você pode verificar e, opcionalmente, atualizar o Google Play Services para a versão exigida pelo SDK do Firebase Unity antes de chamar qualquer outro método 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 Unity está registrado e configurado para usar o Firebase.

Habilite notificações push nas plataformas Apple

Etapa 1: adicionar estrutura de notificações do usuário

  1. Clique no projeto no Xcode e selecione a guia Geral na área do Editor .

  2. Role para baixo até Linked Frameworks and Libraries e clique no botão + para adicionar uma estrutura.

  3. Na janela que aparece, vá até UserNotifications.framework , clique nessa entrada e clique em Adicionar .

Etapa 2: ativar notificações push

  1. Clique no projeto no Xcode e selecione a guia Capacidades na área do Editor .

  2. Mude as notificações push para ativado .

  3. Role para baixo até Modos de fundo e mude para Ligado .

  4. Marque a caixa de seleção Notificações remotas em Modos de segundo plano .

Inicializar o Firebase Cloud Messaging

A biblioteca Firebase Cloud Message será inicializada ao adicionar manipuladores para os eventos TokenReceived ou MessageReceived .

Após a inicialização, um token de registro é solicitado para a instância do aplicativo cliente. O aplicativo receberá o token com o evento OnTokenReceived , que deverá ser armazenado em cache para uso posterior. Você precisará desse token se quiser direcionar mensagens a esse dispositivo específico.

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

Toda a configuração é assim:

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

Configurando uma atividade de ponto de entrada do Android

No Android, o Firebase Cloud Messaging vem com uma atividade de ponto de entrada personalizada que substitui o UnityPlayerActivity padrão. Se você não estiver usando um ponto de entrada personalizado, essa substituição ocorrerá automaticamente e você não deverá realizar nenhuma ação adicional. Os aplicativos que não usam o ponto de entrada padrão Activity ou que fornecem seus próprios Assets/Plugins/AndroidManifest.xml precisarão de configuração extra.

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

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

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

Configurando uma atividade de ponto de entrada personalizado

Se seu aplicativo não usar o UnityPlayerActivity padrão, você precisará remover o AndroidManifest.xml fornecido e garantir que sua atividade personalizada lide adequadamente com todas as transições do ciclo de vida da atividade Android (um exemplo de como fazer isso é mostrado abaixo). Se sua atividade personalizada estender UnityPlayerActivity você poderá estender com.google.firebase.MessagingUnityPlayerActivity , que implementa todos os métodos necessários.

Se você estiver usando uma atividade personalizada e não estendendo com.google.firebase.MessagingUnityPlayerActivity , inclua os seguintes snippets em 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);
}

Novas versões do Firebase C++ SDK (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>

Nota sobre entrega de mensagens no Android

Quando o aplicativo não está em execução e um usuário toca em uma notificação, a mensagem não é, por padrão, roteada por meio dos retornos de chamada integrados do FCM. Nesse caso, as cargas úteis das mensagens são recebidas 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 na bandeja do sistema, mas esse conteúdo da notificação não será comunicado ao FCM. Ou seja, FirebaseMessage.Notification será nulo.

Resumindo:

Estado do aplicativo Notificação Dados Ambos
Primeiro plano Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
Fundo Bandeja do sistema Firebase.Messaging.FirebaseMessaging.MessageReceived Notificação: bandeja do sistema
Dados: em extras da intenção.

Impedir a inicialização automática

O FCM gera um token de registro para segmentação por dispositivo. Quando um token é gerado, a biblioteca carrega o identificador e os dados de configuração para o Firebase. Se quiser obter uma aceitação explícita antes de usar o token, você pode impedir a geração no momento da configuração desativando o FCM (e no Android, o Analytics). Para fazer isso, adicione um valor de metadados ao seu Info.plist (não ao seu GoogleService-Info.plist ) na Apple ou ao seu 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>

Rápido

FirebaseMessagingAutoInitEnabled = NO

Para reativar o FCM, você pode fazer uma chamada de tempo de execução:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Esse valor persiste nas reinicializações do aplicativo, uma vez definido.

O FCM permite o envio de mensagens contendo um link direto para seu aplicativo. Para receber mensagens que contenham um link direto, você deve adicionar um novo filtro de intent à atividade que gerencia links diretos para seu aplicativo. O filtro de intenção deve capturar links diretos do seu domínio. Se suas mensagens não contiverem um link direto, essa configuração não será necessária. Em 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 curinga para tornar o filtro de intenções 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 contendo um link para o esquema e host especificados, seu aplicativo iniciará a atividade com esse filtro de intent para processar o link.

Próximos passos

Depois de configurar o aplicativo cliente, você estará pronto para enviar mensagens downstream e de tópico com o Firebase. Para saber mais, consulte o exemplo de início rápido que demonstra essa funcionalidade.

Para adicionar outro comportamento mais avançado ao seu aplicativo, consulte os guias para enviar mensagens de um servidor de aplicativos:

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