Configurar una aplicación cliente de Firebase Cloud Messaging con Unity

Para escribir tu aplicación cliente multiplataforma de Firebase Cloud Messaging con Unity, usa la API de Firebase Cloud Messaging . El SDK de Unity funciona tanto para Android como para Apple, y se requiere alguna configuración adicional para cada plataforma.

Antes de que empieces

Requisitos previos

  • Instale Unity 2019.1 o posterior. Las versiones anteriores también pueden ser compatibles, pero no tendrán soporte activo. La compatibilidad con Unity 2019.1 se considera obsoleta y ya no se admitirá activamente después de la próxima versión importante.

  • (Solo plataformas Apple) Instale lo siguiente:

    • Xcode 13.3.1 o superior
    • CocoaPods 1.12.0 o superior
  • Asegúrese de que su proyecto de Unity cumpla con estos requisitos:

    • Para iOS : apunta a iOS 11 o superior
    • Para tvOS : apunta a tvOS 12 o superior
    • Para Android : apunta al nivel API 19 (KitKat) o superior
  • Configure un dispositivo o use un emulador para ejecutar su proyecto de Unity.

    • Para iOS o tvOS : configure un dispositivo físico para ejecutar su aplicación y complete estas tareas:

      • Obtenga una clave de autenticación de notificaciones push de Apple para su cuenta de desarrollador de Apple .
      • Habilite las notificaciones push en XCode en Aplicación > Capacidades .
    • Para Android : los emuladores deben utilizar una imagen de emulador con Google Play.

Si aún no tienes un proyecto de Unity y solo quieres probar un producto de Firebase, puedes descargar uno de nuestros ejemplos de inicio rápido .

Paso 1: crea un proyecto de Firebase

Antes de poder agregar Firebase a su proyecto de Unity, debe crear un proyecto de Firebase para conectarse a su proyecto de Unity. Visita Comprender los proyectos de Firebase para obtener más información sobre los proyectos de Firebase.

Paso 2: registra tu aplicación en Firebase

Puedes registrar una o más aplicaciones o juegos para conectarlos con tu proyecto de Firebase.

  1. Vaya a la consola de Firebase .

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

    Si ya agregó una aplicación a su proyecto de Firebase, haga clic en Agregar aplicación para mostrar las opciones de la plataforma.

  3. Seleccione qué objetivo de compilación de su proyecto de Unity desea registrar, o incluso puede seleccionar registrar ambos objetivos ahora al mismo tiempo.

  4. Ingrese los ID específicos de la plataforma de su proyecto de Unity.

    • Para iOS : ingresa el ID de iOS de tu proyecto de Unity en el campo ID del paquete de iOS .

    • Para Android : ingrese el ID de Android de su proyecto de Unity en el campo de nombre del paquete de Android .
      Los términos nombre de paquete e ID de aplicación suelen utilizarse indistintamente.

  5. (Opcional) Ingrese los apodos específicos de la plataforma de su proyecto de Unity.
    Estos apodos son identificadores internos y prácticos y solo usted puede verlos en Firebase console.

  6. Haga clic en Registrar aplicación .

Paso 3: agregar archivos de configuración de Firebase

  1. Obtenga los archivos de configuración de Firebase específicos de su plataforma en el flujo de trabajo de configuración de la consola de Firebase.

    • Para iOS : haga clic en Descargar GoogleService-Info.plist .

    • Para Android : haga clic en Descargar google-services.json .

  2. Abra la ventana Proyecto de su proyecto de Unity, luego mueva su(s) archivo(s) de configuración a la carpeta Assets .

  3. De vuelta en Firebase console, en el flujo de trabajo de configuración, haz clic en Siguiente .

Paso 4: Agregar los SDK de Firebase Unity

  1. En Firebase console, haga clic en Descargar Firebase Unity SDK y luego descomprima el SDK en algún lugar conveniente.

    • Puedes descargar el SDK de Firebase Unity nuevamente en cualquier momento.

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

  2. En su proyecto abierto de Unity, navegue hasta Activos > Importar paquete > Paquete personalizado .

  3. Desde el SDK descomprimido, seleccione los productos de Firebase compatibles que desea usar en su aplicación.

    Para una experiencia óptima con Firebase Cloud Messaging, recomendamos habilitar Google Analytics en su proyecto. Además, como parte de la configuración de Analytics, debes agregar el paquete Firebase para Analytics a tu aplicación.

    Análisis habilitado

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

    Análisis no habilitado

    Agregue el paquete para Firebase Cloud Messaging: FirebaseMessaging.unitypackage

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

  5. De vuelta en Firebase console, en el flujo de trabajo de configuración, haz clic en Siguiente .

Paso 5: Confirme los requisitos de versión de los servicios de Google Play

El SDK de Firebase Unity para Android requiere los servicios de Google Play , que deben estar actualizados antes de poder utilizar el SDK.

Agregue lo siguiente using la declaración y el código de inicialización al inicio de su aplicación. Puede verificar y, opcionalmente, actualizar los servicios de Google Play a la versión requerida por el SDK de Firebase Unity antes de llamar a cualquier otro método 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.
  }
});

Su proyecto de Unity está registrado y configurado para usar Firebase.

Habilite las notificaciones push en las plataformas Apple

Paso 1: agregar el marco de notificaciones de usuario

  1. Haga clic en el proyecto en Xcode, luego seleccione la pestaña General del área Editor .

  2. Desplácese hacia abajo hasta Bibliotecas y marcos vinculados y luego haga clic en el botón + para agregar un marco.

  3. En la ventana que aparece, desplácese hasta UserNotifications.framework , haga clic en esa entrada y luego haga clic en Agregar .

Paso 2: habilite las notificaciones automáticas

  1. Haga clic en el proyecto en Xcode, luego seleccione la pestaña Capacidades del área Editor .

  2. Cambie las notificaciones automáticas a Activadas .

  3. Desplázate hacia abajo hasta Modos de fondo y luego cámbialo a Activado .

  4. Seleccione la casilla de verificación Notificaciones remotas en Modos de fondo .

Inicializar la mensajería en la nube de Firebase

La biblioteca Firebase Cloud Message se inicializará al agregar controladores para los eventos TokenReceived o MessageReceived .

Tras la inicialización, se solicita un token de registro para la instancia de la aplicación cliente. La aplicación recibirá el token con el evento OnTokenReceived , que deberá almacenarse en caché para su uso posterior. Necesitará este token si desea dirigir los mensajes a este dispositivo específico.

Además, deberá registrarse en el evento OnMessageReceived si desea poder recibir mensajes entrantes.

Toda la configuración se ve así:

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

Configurar una actividad de punto de entrada de Android

En Android, Firebase Cloud Messaging viene con una actividad de punto de entrada personalizada que reemplaza la UnityPlayerActivity predeterminada. Si no utiliza un punto de entrada personalizado, este reemplazo se produce automáticamente y no debería tener que realizar ninguna acción adicional. Las aplicaciones que no utilizan el punto de entrada predeterminado Actividad o que proporcionan sus propios Assets/Plugins/AndroidManifest.xml necesitarán una configuración adicional.

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

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

Estos archivos se proporcionan porque el UnityPlayerActivity predeterminado no maneja las transiciones del ciclo de vida de la actividad onStop y onRestart ni implementa el onNewIntent que es necesario para que Firebase Cloud Messaging maneje correctamente los mensajes entrantes.

Configurar un punto de entrada personalizado Actividad

Si su aplicación no utiliza UnityPlayerActivity predeterminada, deberá eliminar el AndroidManifest.xml proporcionado y asegurarse de que su actividad personalizada maneje correctamente todas las transiciones del ciclo de vida de la actividad de Android (a continuación se muestra un ejemplo de cómo hacerlo). Si su actividad personalizada extiende UnityPlayerActivity puede extender com.google.firebase.MessagingUnityPlayerActivity , que implementa todos los métodos necesarios.

Si está utilizando una Actividad personalizada y no extiende com.google.firebase.MessagingUnityPlayerActivity , debe incluir los siguientes fragmentos en su 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 nuevas versiones del SDK de Firebase C++ (7.1.0 en adelante) 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 aplicación no se está ejecutando y un usuario toca una notificación, el mensaje, de forma predeterminada, no se enruta a través de las devoluciones de llamada integradas de FCM. En este caso, las cargas de mensajes se reciben a través de un Intent utilizado para iniciar la aplicación.

Los mensajes recibidos mientras la aplicación está en segundo plano tienen el contenido de su campo de notificación utilizado para completar la notificación de la bandeja del sistema, pero el contenido de la notificación no se comunicará a FCM. Es decir, FirebaseMessage.Notification será nulo.

En resumen:

Estado de la aplicación 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 de la intención.

Prevenir la inicialización automática

FCM genera un token de registro para la orientación por dispositivo. Cuando se genera un token, la biblioteca carga el identificador y los datos de configuración en Firebase. Si desea obtener una suscripción explícita antes de usar el token, puede evitar su generación en el momento de la configuración desactivando FCM (y en Android, Analytics). Para hacer esto, agregue un valor de metadatos a su Info.plist (no a su GoogleService-Info.plist ) en Apple, o a su AndroidManifest.xml en Android:

Androide

<?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 volver a habilitar FCM, puede realizar una llamada en tiempo de ejecución:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

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

FCM permite enviar mensajes que contengan un enlace profundo a su aplicación. Para recibir mensajes que contengan un vínculo profundo, debe agregar un nuevo filtro de intención a la actividad que maneja vínculos profundos para su aplicación. El filtro de intención debería detectar enlaces profundos de su dominio. Si sus mensajes no contienen un enlace profundo, 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 que el filtro de intención sea más flexible. 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 tocan una notificación que contiene un enlace al esquema y al host que usted especifica, su aplicación iniciará la actividad con este filtro de intención para manejar el enlace.

Próximos pasos

Después de configurar la aplicación cliente, estará listo para enviar mensajes posteriores y temáticos con Firebase. Para obtener más información, consulte el ejemplo de inicio rápido que demuestra esta funcionalidad.

Para agregar otro comportamiento más avanzado a su aplicación, consulte las guías para enviar mensajes desde un servidor de aplicaciones:

Tenga en cuenta que necesitará una implementación de servidor para utilizar estas funciones.