Configura una app cliente de Firebase Cloud Messaging con Unity

Para escribir tu app cliente multiplataforma de Firebase Cloud Messaging con Unity, usa la API de Firebase Cloud Messaging. El SDK de Unity es compatible con Apple y Android, pero se necesitan algunos pasos de configuración adicionales en cada plataforma.

Antes de comenzar

Requisitos previos

  • Instala Unity 2019.1 o una versión más reciente. Las versiones anteriores pueden ser compatibles, pero no de forma activa. La compatibilidad con Unity 2019.1 se considera obsoleta y ya no se admitirá de forma activa después de la próxima actualización importante.

  • Instala los siguientes servicios (solo en plataformas de Apple):

    • Xcode 13.3.1 o una versión más reciente
    • CocoaPods 1.10.0 o una versión más reciente
  • Asegúrate de que tu proyecto de Unity cumpla con estos requisitos:

    • iOS: El sistema objetivo debe ser iOS 11 o una versión más reciente.
    • tvOS: El sistema objetivo debe ser tvOS 12 o una versión más reciente.
    • Android: El nivel de API objetivo debe ser 19 (KitKat) o una versión más reciente.
  • Configura un dispositivo o usa un emulador para ejecutar tu proyecto de Unity.

    • iOS o tvOS: Configura un dispositivo físico para ejecutar la app y completa las siguientes tareas:

      • Obtén una clave de autenticación de notificaciones push de Apple para tu cuenta de Apple Developer.
      • En Xcode, habilita las notificaciones push en App > Capabilities.
    • Android: Los emuladores deben usar una imagen que cuente con Google Play.

Si solo quieres probar un producto de Firebase, pero aún no tienes un proyecto de Unity, puedes descargar una de estas muestras de inicio rápido.

Paso 1: Crea un proyecto de Firebase

Antes de que puedas agregar Firebase al proyecto de Unity, deberás crear un proyecto de Firebase para conectarlo con el de Unity. Consulta Información sobre los proyectos de Firebase para obtener detalles acerca del tema.

Paso 2: Registra tu app con Firebase

Puedes registrar una o más apps o juegos para conectarlos con el proyecto de Firebase.

  1. Dirígete a Firebase console.

  2. En el centro de la página de descripción general del proyecto, haz clic en el ícono de Unity () para iniciar el flujo de trabajo de configuración.

    Si ya agregaste una app a tu proyecto de Firebase, haz clic en Agregar app para que se muestren las opciones de plataforma.

  3. Selecciona qué destino de compilación del proyecto de Unity quieres registrar. Si quieres registrar ambos destinos a la vez, este es el momento de hacerlo.

  4. Ingresa el ID del proyecto de Unity específico de cada plataforma.

    • iOS: Ingresa el ID de iOS del proyecto de Unity en el campo ID del paquete de iOS.

    • Android: Ingresa el ID de Android del proyecto de Unity en el campo Nombre del paquete de Android.
      Por lo general, los términos ID de la aplicación y nombre del paquete se utilizan de manera intercambiable.

  5. Ingresa el sobrenombre específico de cada plataforma para el proyecto de Unity (opcional).
    Los sobrenombres son identificadores internos y convenientes que solo tú puedes ver en Firebase console.

  6. Haz clic en Registrar app.

Paso 3: Agrega los archivos de configuración de Firebase

  1. Usa el flujo de trabajo de configuración de Firebase console para obtener los archivos de configuración de Firebase específicos de las plataformas.

    • iOS: Haz clic en Download GoogleService-Info.plist.

    • Android: Haz clic en Download google-services.json.

  2. Abre la ventana Project del proyecto de Unity y transfiere los archivos de configuración a la carpeta Assets.

  3. Vuelve a Firebase console y, en el flujo de trabajo de configuración, haz clic en Siguiente.

Paso 4: Agrega los SDK de Firebase Unity

  1. En Firebase console, haz clic en Descargar el SDK de Firebase Unity y descomprímelo en el lugar que prefieras.

    • Puedes volver a descargar el SDK de Firebase Unity cuando quieras.

    • El SDK de Firebase Unity no es específico para cada plataforma.

  2. Abre tu proyecto de Unity, ve a Elementos > Importar paquete > Paquete personalizado.

  3. En el SDK descomprimido, selecciona los productos de Firebase admitidos que deseas usar en la app.

    Para obtener una experiencia óptima con Firebase Cloud Messaging, recomendamos habilitar Google Analytics en tu proyecto. Además, debes agregar el paquete de Firebase para Analytics a la app cuando configures Analytics.

    Si Analytics está habilitado

    • Agrega el paquete de Firebase para Google Analytics: FirebaseAnalytics.unitypackage.
    • Agrega el paquete de Firebase Cloud Messaging: FirebaseMessaging.unitypackage.

    Si Analytics está inhabilitado

    Agrega el paquete de Firebase Cloud Messaging: FirebaseMessaging.unitypackage.

  4. En la ventana Import Unity Package, haz clic en Import.

  5. Vuelve a Firebase console y, en el flujo de trabajo de configuración, haz clic en Siguiente.

Paso 5: Confirma los requisitos de la versión de los Servicios de Google Play

El SDK de Firebase Unity en Android requiere los Servicios de Google Play actualizados para poder usarlo.

Se debe agregar el siguiente código al inicio de la aplicación. Puedes buscar los Servicios de Google Play y, de forma opcional, actualizarlos a la versión que requiera el SDK de Firebase Unity. De esta manera, es posible llamar a otros métodos en el 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.
  }
});

El proyecto de Unity se registró y configuró para usar Firebase.

Habilita las notificaciones push en las plataformas de Apple

Paso 1: Agrega el framework de notificaciones de usuario

  1. Haz clic en el proyecto en Xcode y selecciona la pestaña General en Editor area.

  2. Desplázate hacia abajo hasta Linked Frameworks and Libraries y selecciona el botón + para agregar un framework.

  3. En la ventana que aparece, desplázate hasta UserNotifications.framework, haz clic en esa entrada y, luego, en Add.

Paso 2: Habilita las notificaciones push

  1. Haz clic en el proyecto en Xcode y selecciona la pestaña Capabilities en Editor area.

  2. Activa Push Notifications.

  3. Desplázate a Background Modes y activa esa opción.

  4. Selecciona la casilla de verificación Remote Notifications en Background Modes.

Inicializa Firebase Cloud Messaging

La biblioteca de Firebase Cloud Messaging se inicializará cuando agregues controladores para eventos TokenReceived o MessageReceived.

Tras la inicialización, se solicita un token de registro para la instancia de la app cliente. La app recibirá el token con el evento OnTokenReceived, que debe almacenarse en caché para usarse después. Necesitarás este token si quieres orientar mensajes a este dispositivo específico.

Además, deberás registrar el evento OnMessageReceived si deseas recibir mensajes entrantes.

La configuración completa tiene el siguiente aspecto:

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

Configura una actividad de punto de entrada de Android

En Android, Firebase Cloud Messaging incluye una actividad de punto de entrada personalizado que reemplaza la predeterminada (UnityPlayerActivity). Si no usas un punto de entrada personalizado, este reemplazo se aplica de forma automática y no debes hacer nada más. Las apps que no usan la actividad de punto de entrada predeterminado o que incluyen su propio Assets/Plugins/AndroidManifest.xml requieren pasos de configuración adicionales.

El complemento de Firebase Cloud Messaging para Unity en Android viene con dos archivos adicionales:

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar contiene una actividad llamada MessagingUnityPlayerActivity que reemplaza la UnityPlayerActivity estándar.
  • Assets/Plugins/Android/AndroidManifest.xml le indica a la app que use MessagingUnityPlayerActivity como punto de entrada de la app.

Se incluyen estos archivos porque la actividad predeterminada UnityPlayerActivity no controla las transiciones del ciclo de vida de las actividades onStop y onRestart, ni implementa onNewIntent, lo cual es necesario para que Firebase Cloud Messaging administre correctamente los mensajes entrantes.

Configura una actividad de punto de entrada personalizado

Si la app no usa la actividad predeterminada UnityPlayerActivity, deberás quitar el archivo AndroidManifest.xml que se proporciona y asegurarte de que la actividad personalizada maneje correctamente todas las transiciones del ciclo de vida de las actividades de Android (a continuación, se muestra un ejemplo de cómo hacerlo). Si la actividad personalizada extiende UnityPlayerActivity, puedes extender com.google.firebase.MessagingUnityPlayerActivity en su lugar, ya que esta actividad implementa todos los métodos necesarios.

Si usas una actividad personalizada y no extiendes com.google.firebase.MessagingUnityPlayerActivity, debes incluir los siguientes fragmentos en la actividad.

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

Las versiones nuevas del SDK de Firebase C++ (7.1.0 y posteriores) usan JobIntentService, que requiere modificaciones adicionales en el archivo AndroidManifest.xml.

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

Nota sobre la entrega de mensajes en Android

Cuando la app no se está ejecutando en absoluto y un usuario presiona una notificación, el mensaje no se envía, según la configuración predeterminada, a través de las devoluciones de llamada incorporadas en FCM. En este caso, las cargas útiles de los mensajes se reciben a través de un Intent que se usa para iniciar la aplicación.

Los mensajes que se reciben mientras la app se ejecuta en segundo plano incluyen el contenido del campo de notificación que se usó para propagar la notificación de la bandeja del sistema. Sin embargo, no se comunicará el contenido de la notificación a FCM. Es decir, FirebaseMessage.Notification tendrá un valor nulo.

Resumen:

Estado de la app Notificación Datos Ambos
Primer plano Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
Segundo plano Bandeja del sistema Firebase.Messaging.FirebaseMessaging.MessageReceived Notificación: Bandeja del sistema
Datos: En extras del intent.

Evita la inicialización automática

FCM genera un token de registro para la segmentación por dispositivo. Cuando se genera un token, la biblioteca sube el identificador y los datos de configuración a Firebase. Si deseas obtener una habilitación explícita antes de usar el token, puedes evitar que se genere en el momento de la configuración inhabilitando FCM (y Analytics en Android). Para ello, agrega un valor de metadatos a Info.plist (no a GoogleService-Info.plist) en Apple, o a AndroidManifest.xml en Android, como se muestra a continuación:

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 volver a habilitar FCM, realiza una llamada de tiempo de ejecución, de la siguiente manera:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Este valor persiste en todos los reinicios de la aplicación una vez establecido.

FCM permite enviar mensajes que contengan un vínculo directo a una app. Para recibir mensajes que contengan un vínculo directo, debes agregar un filtro de intents nuevo a la actividad que administra los vínculos directos para tu app. El filtro de intent debe capturar vínculos directos del dominio. Si los mensajes no contienen un vínculo directo, esta configuración no es necesaria. En 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>

También es posible especificar un comodín para aumentar la flexibilidad del filtro de intent. Por ejemplo:

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

Cuando los usuarios presionen una notificación con un vínculo al esquema y al host que especificaste, tu app iniciará la actividad con este filtro de intent para administrar el vínculo.

Pasos siguientes

Después de configurar la app cliente, estás listo para enviar mensajes descendentes y a temas con Firebase. Para obtener más información, consulta la muestra de inicio rápido, que demuestra esta función.

Para agregar otro comportamiento más avanzado a tu app, consulta las guías para enviar mensajes desde un servidor de apps:

Recuerda que necesitarás una implementación de servidor para usar estas funciones.