Ir para o console

Configurar um app cliente do Firebase Cloud Messaging com o Unity

Para gravar seu aplicativo cliente multiplataforma 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

Etapa 1: configurar seu ambiente

  • Instale o Unity 5.3 ou posterior.

  • (somente iOS) Garanta que você tem acesso ao seguinte:

    • Xcode 9.4.1 ou posterior
    • CocoaPods 1.4.0 ou posterior
  • Garanta que seu projeto Unity segmente o nível de sistema operacional adequado:

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

    • Para iOS: para o Firebase Cloud Messaging, você precisará de:

      • Um dispositivo físico com iOS
      • Certificado de APNs com notificações push ativadas
    • 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 tiver um projeto do Unity e quiser testar um produto do Firebase, faça o download de um dos nossos exemplos para início rápido (em inglês).

Etapa 2: 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. Visite Noções básicas sobre projetos do Firebase para entender melhor.

Etapa 3: registrar seu projeto Unity com o Firebase

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

  1. No centro da página de visão geral do projeto do 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. ID de exemplo: 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 código do pacote do iOS (em inglês).

      • Para Android: insira o ID do Android do seu projeto do Unity no campo Nome do pacote do 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 Register app.

Etapa 4: adicionar arquivos de configuração do Firebase ao seu projeto do Unity

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

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

    • Antes de mover seu arquivo de configuração, verifique se não há caracteres adicionais anexados a ele, como (2).
    • É possível colocar os arquivos de configuração do Firebase em qualquer lugar da pasta Assets.
  3. De volta ao Console do Firebase, em configuração de fluxo de trabalho, clique em Próximo.

Etapa 5: adicionar um SDK do Firebase ao seu projeto do Unity

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

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

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

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

  3. No SDK descompactado, selecione a opção para importar o SDK do Firebase Cloud Messaging (FirebaseMessaging.unitypackage).

    Também é possível importar qualquer outro produto do Firebase compatível.

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

  5. De volta ao fluxo de trabalho de configuração no Console do Firebase, clique em Próxima.

Etapa 6: 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

  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 uma biblioteca.

  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 são adicionados gerenciadores 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, e é necessário armazená-lo em cache para uso posterior. Você precisa desse token se quiser direcionar esse dispositivo específico para mensagens.

Além disso, registre-se no evento OnMessageReceived para 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:

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

Esses arquivos são fornecidos porque o padrão UnityPlayerActivity não gerencia transições de ciclo de vida da atividade onStop ou onRestart nem implementa onNewIntent, que é necessário para que o Firebase Cloud Messaging gerencie 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 de atividades do Android (em inglês). Veja abaixo um exemplo desse procedimento. Se a atividade personalizada estender o UnityPlayerActivity, amplie com.google.firebase..MessagingUnityPlayerActivity, que implementa todos os métodos necessários.

Se você usar uma atividade personalizada sem estender o com.google.firebase.MessagingUnityPlayerActivity, inclua 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
 * receieved 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 a 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 o 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
Segundo plano 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 código 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 você quer 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, você precisa 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:

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