Configurar um app cliente do Firebase Cloud Messaging com o Unity

Para gravar seu aplicativo cliente multiplataforma do Firebase Cloud Messaging com o Unity, use a API Firebase Cloud Messaging. O SDK do Unity funciona para Android e iOS, com alguma configuração adicional necessária em cada plataforma.

Antes de começar

Pré-requisitos

  • Instale o Unity 5.3 ou posterior.

  • Instale os seguintes itens (somente para iOS):

  • Xcode 9.4.1 ou posterior
  • CocoaPods 1.4.0 ou posterior
  • Verifique se seu projeto do Unity atende aos requisitos a seguir:

  • Para iOS: segmenta o iOS 8 ou posterior
  • Para Android: segmenta o nível 16 da API (Jelly Bean) ou posterior
  • Configure um dispositivo ou emulador para executar seu projeto do Unity.

    • Para iOS: configure um dispositivo físico com iOS ou o simulador iOS para executar seu app.

      • Para o Cloud Messaging, conclua as seguintes tarefas:

      • Configure um dispositivo físico com iOS.
      • 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 todos os outros produtos do Firebase, é possível usar um dispositivo físico com iOS ou o simulador de iOS.

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

  • Faça login no Firebase usando 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 um dos nossos exemplos de guia de início rápido (em inglês).

    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.

    Crie um projeto do Firebase

    1. No Console do Firebase, clique em Adicionar projeto e depois selecione ou insira o Nome do projeto.

      Se você tiver um projeto do Google Cloud Platform (GCP), poderá selecionar o projeto no menu suspenso para adicionar recursos do Firebase ao projeto em questão.

    2. Se você criou um novo projeto, poderá editar o ID dele (opcional).

      O Firebase atribui automaticamente um ID exclusivo ao seu projeto. Consulte Noções básicas sobre projetos do Firebase para entender melhor como o Firebase usa o ID do projeto.

    3. Clique em Continuar.

    4. (Opcional) Configure o Google Analytics para seu projeto, permitindo que você tenha uma ótima experiência ao usar qualquer um dos seguintes produtos do Firebase:

    5. Firebase Crashlytics
    6. Firebase Previsões
    7. Firebase Cloud Messaging
    8. Mensagens no app do Firebase
    9. Configuração remota do Firebase
    10. Teste A/B do Firebase
    11. Quando solicitado, selecione para usar uma Conta do Google Analytics ou criar uma nova conta.
      Se você decidir criar uma nova conta, selecione seu local de relatórios do Analytics e aceite as configurações de compartilhamento de dados e os termos do Google Analytics relacionados ao seu projeto.

    12. Clique em Criar projeto (ou Adicionar Firebase, se você estiver usando um projeto do GCP).

    13. O Firebase provisiona recursos automaticamente para seu projeto. Quando o processo for concluído, você será direcionado para a página de visão geral do seu projeto no Console do Firebase.

      Etapa 2: registrar seu projeto do Unity com o Firebase

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

      1. No centro da página de visão geral do projeto no Console do Firebase, 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.

      2. Selecione qual destino de versão do seu projeto Unity você quer registrar ou pode optar por registrar os dois destinos agora.

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

        1. Abra seu projeto do Unity no seu ambiente de desenvolvimento integrado do Unity.

        2. Navegue até Build Settings > iOS ou Android > Player Settings > Other Settings.

          O ID do projeto do Unity é o valor de Bundle Identifier. Exemplo de ID: com.yourcompany.unity-project-name

        3. Digite cada ID específico da plataforma no campo apropriado:

          • Para iOS: insira o ID do iOS do seu projeto do Unity no campo ID do pacote iOS (em inglês).

          • 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.
      4. (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.

      5. Clique em Registrar app.

      6. Etapa 3: adicionar os arquivos de configuração do Firebase ao seu projeto do Unity

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

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

        3. Antes de mover seus arquivos de configuração, verifique se não há caracteres adicionais anexados a eles, como (2).
        4. É possível colocar os arquivos de configuração do Firebase em qualquer lugar na pasta Assets.
        5. De volta ao fluxo de trabalho de configuração no Console do Firebase, clique em Avançar.

        6. Etapa 4: adicionar um SDK do Firebase ao seu projeto do 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.

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

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

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

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

            Para uma experiência ideal com o Firebase Cloud Messaging, recomendamos ativar o Google Analytics no seu projeto. Como parte da configuração do Google Analytics, é necessário adicionar o pacote do Firebase para o Google Analytics ao seu aplicativo.

            Analytics ativado

          6. Adicione o pacote do Firebase para o Google Analytics: FirebaseAnalytics.unitypackage
          7. Adicione o pacote para o Firebase Cloud Messaging: FirebaseMessaging.unitypackage
          8. Analytics não ativado

            Adicione o pacote para o Firebase Cloud Messaging: FirebaseMessaging.unitypackage

            A versão 5.x do Unity e anteriores usam o framework .NET 3.x. Portanto, importe o pacote dotnet3/.

            A versão 2017.x do Unity e posteriores permitem o uso do framework .NET 4.x. Caso seu projeto do Unity use .NET 4.x, importe o pacote dotnet4/.

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

          10. 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 para Unity do Firebase 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 para Unity do Firebase 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 do Unity é registrado e configurado para usar o Firebase.

          Etapa 7: adicionar a biblioteca de notificações do usuário

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

        8. Role para baixo até Linked Frameworks and Libraries e clique no botão com o símbolo + para adicionar uma biblioteca.

        9. Na janela exibida, role até UserNotifications.framework e clique nessa entrada. Depois, clique em Add.

        10. Etapa 8: ativar as notificações push

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

        12. Mude Push Notifications para On.

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

        14. Marque a caixa Remote notifications em Background Modes.

        15. 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 do cliente. O app recebe o token com o evento OnTokenReceived, que precisa ser armazenado em cache para uso posterior. Esse token será necessário para segmentar 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 personalizada que substitui o UnityPlayerActivity padrão. Se você não estiver usando um ponto de entrada personalizado, essa substituição acontece automaticamente e você não precisa de nenhuma ação adicional. 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:

        16. O Assets/Plugins/Android/libmessaging_unity_player_activity.jar contém uma atividade chamada MessagingUnityPlayerActivity que substitui o UnityPlayerActivity padrão.
        17. O Assets/Plugins/Android/AndroidManifest.xml instrui o app a usar MessagingUnityPlayerActivity como o ponto de entrada para o app.
        18. Esses arquivos são fornecidos porque o UnityPlayerActivity padrão não processa transições de ciclo de vida da atividade onStop e onRestart ou 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 o UnityPlayerActivity padrão, remova o AndroidManifest.xml fornecido e verifique se a atividade personalizada gerencia corretamente todas as transições do ciclo de vida da atividade do Android (em inglês). Veja abaixo um exemplo desse procedimento. Se sua atividade personalizada estender o UnityPlayerActivity, você poderá estender o com.google.firebase.MessagingUnityPlayerActivity, que implementa todos os métodos necessários.

          Se você estiver usando uma atividade personalizada e não estender o 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());
            startService(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);
          }
          

          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 retornos de chamada incorporados do FCM. Nesse caso, os payloads das mensagens são recebidos por meio de um Intent usado 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:

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

          Impedir a inicialização automática

          O FCM gera um ID de instância que é usado como um token de registro no FCM. Quando ele é gerado, a biblioteca faz upload dos dados de configuração e do identificador para o Firebase. Se quiser receber uma confirmação antes de usar o código da instância, é possível impedir a geração dele desativando o FCM (e, no Android, o Analytics). Para isso, adicione um valor de metadados ao seu Info.plist (não ao seu GoogleService-Info.plist) no iOS 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>

          iOS

          FirebaseMessagingAutoInitEnabled = NO

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

          Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;
          

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

          O FCM permite que mensagens sejam enviadas contendo 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 de início rápido 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:

        19. Enviar mensagens de tópico
        20. Enviar a grupos de dispositivos
        21. Enviar mensagens upstream
        22. Saiba que você precisará de uma implementação de servidor para usar esses recursos.