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 funciona tanto en Android como en Apple, aunque se requieren ciertos ajustes adicionales en la configuración para cada plataforma.

Antes de comenzar

Requisitos previos

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

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

    • Xcode 13.3.1 o una versión más reciente
    • CocoaPods 1.12.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 13 o una versión más reciente.
    • tvOS: El sistema objetivo debe ser tvOS 13 o una versión más reciente.
    • Para Android: Se segmenta al nivel de API 21 (Lollipop) o una versión posterior.

  • 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. Ir 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 Unity de Firebase y, luego, descomprime el SDK en el lugar que prefieras.

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

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

  2. Abre el 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, te recomendamos que habilites Google Analytics en tu proyecto. Además, como parte de la configuración de Analytics, debes agregar el paquete de Firebase de Analytics a tu app.

    Analytics habilitado

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

    Analytics no habilitado

    Agrega el paquete para Firebase Cloud Messaging: FirebaseMessaging.unitypackage

  4. En la ventana Importar paquete de Unity, haz clic en Importar.

  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 para Android requiere los Google Play services actualizados para poder usarlo.

Agrega la siguiente sentencia using y el código de inicialización al comienzo de tu aplicación. Puedes buscar los Google Play services 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.

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

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

Sube la clave de autenticación de APNs para el equipo de soporte técnico de Apple

Sube la clave de autenticación del APNS a Firebase. Si aún no tienes una, asegúrate de crearla en el Centro para miembros de Apple Developer.

  1. Dentro del proyecto en Firebase console, selecciona el ícono de ajustes, elige Configuración del proyecto y, luego, la pestaña Cloud Messaging.

  2. En Clave de autenticación de APNS, en iOS app configuration, haz clic en el botón Subir.

  3. Busca la ubicación en la que guardaste la clave, selecciónala y haz clic en Abrir. Agrega el ID de clave correspondiente (disponible en el centro para miembros de Apple Developer) y haz clic en Subir.

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 UnityPlayerActivity predeterminada. 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
Fondo 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 intents 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.

Próximos pasos

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.