Configurare un'app client Firebase Cloud Messaging con Unity

Per scrivere la tua app client Firebase Cloud Messaging multipiattaforma con Unity, utilizza l'API Firebase Cloud Messaging. L'SDK Unity funziona sia per Android che per Apple, con alcune configurazioni aggiuntive necessarie per ogni piattaforma.

Prima di iniziare

Prerequisiti

  • Installa Unity 2021 LTS o versioni successive. Il supporto per Unity 2020 è considerato deprecato e non sarà più supportato attivamente dopo la prossima release principale. Anche le versioni precedenti potrebbero essere compatibili, ma non saranno supportate attivamente.

  • (Solo piattaforme Apple) Installa quanto segue:

    • Xcode 13.3.1 o versioni successive
    • CocoaPods 1.12.0 o versioni successive

  • Assicurati che il progetto Unity soddisfi questi requisiti:

    • Per iOS: target iOS 13 o versioni successive
    • Per tvOS: target tvOS 13 o versioni successive
    • Per Android: ha come target il livello API 21 (Lollipop) o versioni successive

  • Configura un dispositivo o utilizza un emulatore per eseguire il progetto Unity.

    • Per iOS o tvOS: configura un dispositivo fisico per eseguire la tua app e completa le seguenti attività:

      • Ottieni una chiave di autenticazione per le notifiche push di Apple per il tuo account sviluppatore Apple.
      • Attiva le notifiche push in XCode sotto App > Funzionalità.

    • Per Android: gli emulatori devono utilizzare un'immagine emulatore con Google Play.

Se non disponi già di un progetto Unity e vuoi semplicemente provare un prodotto Firebase, puoi scaricare uno dei nostri esempi di guida rapida.

Passaggio 1: crea un progetto Firebase

Prima di poter aggiungere Firebase al tuo progetto Unity, devi creare un progetto Firebase da collegare al progetto Unity. Per saperne di più sui progetti Firebase, consulta Informazioni sui progetti Firebase.

Passaggio 2: registra la tua app in Firebase

Puoi registrare uno o più giochi o app da collegare al tuo progetto Firebase.

  1. Vai alla console Firebase.

  2. Al centro della pagina di riepilogo del progetto, fai clic sull'icona Unity () per avviare il flusso di lavoro di configurazione.

    Se hai già aggiunto un'app al tuo progetto Firebase, fai clic su Aggiungi app per visualizzare le opzioni della piattaforma.

  3. Seleziona la destinazione di build del tuo progetto Unity che vuoi registrare oppure puoi anche selezionare la registrazione di entrambe le destinazioni contemporaneamente.

  4. Inserisci gli ID specifici della piattaforma del progetto Unity.

    • Per iOS: inserisci l'ID iOS del tuo progetto Unity nel ID gruppo iOS.

    • Per Android: inserisci l'ID Android del progetto Unity nel campo Nome del pacchetto Android.
      I termini nome pacchetto e ID applicazione vengono spesso utilizzati in modo intercambiabile.

  5. (Facoltativo) Inserisci i nickname specifici della piattaforma per il progetto Unity.
    Questi nickname sono identificatori interni di praticità e sono visibili solo nella console Firebase.

  6. Fai clic su Registra app.

Passaggio 3: aggiungi i file di configurazione di Firebase

  1. Ottieni i file di configurazione di Firebase specifici della piattaforma nel Firebase flusso di lavoro di configurazione della console.

    • Per iOS: fai clic su Scarica GoogleService-Info.plist.

    • Per Android: fai clic su Scarica google-services.json.

  2. Apri la finestra Progetto del progetto Unity, quindi sposta i file di configurazione nella cartella Assets.

  3. Torna nella console Firebase e, nel flusso di lavoro di configurazione, fai clic su Avanti.

Passaggio 4: aggiungi gli SDK Firebase Unity

  1. Nella console Firebase, fai clic su Scarica SDK Firebase Unity, quindi decomprimi l'SDK in una posizione comoda.

    • Puoi scaricare di nuovo l'SDK Firebase Unity in qualsiasi momento.

    • L'SDK Firebase Unity non è specifico della piattaforma.

  2. Nel tuo progetto Unity aperto, vai a Asset > Importa pacchetto > Pacchetto personalizzato.

  3. Dall'SDK non compresso, seleziona i prodotti Firebase supportati che vuoi utilizzare nella tua app.

    Per un'esperienza ottimale con Firebase Cloud Messaging, ti consigliamo di abilitare Google Analytics nel tuo progetto. Inoltre, durante la configurazione di Analytics, devi aggiungere il pacchetto Firebase per Analytics alla tua app.

    Analytics abilitato

    • Aggiungi il pacchetto Firebase per Google Analytics: FirebaseAnalytics.unitypackage
    • Aggiungi il pacchetto per Firebase Cloud Messaging: FirebaseMessaging.unitypackage

    Analytics non attivato

    Aggiungi il pacchetto per Firebase Cloud Messaging: FirebaseMessaging.unitypackage

  4. Nella finestra Importa il pacchetto Unity, fai clic su Importa.

  5. Torna nella console Firebase e, nel flusso di lavoro di configurazione, fai clic su Avanti.

Passaggio 5: verifica i requisiti della versione di Google Play Services

L'SDK Firebase Unity per Android richiede Google Play services, che deve essere aggiornato prima che l'SDK possa essere utilizzato.

Aggiungi la seguente dichiarazione using e il codice di inizializzazione all'inizio della applicazione. Puoi verificare e, facoltativamente, aggiornare Google Play services alla versione richiesta dall'SDK Firebase Unity prima di chiamare altri metodi nell'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.
  }
});

Il progetto Unity è registrato e configurato per l'utilizzo di Firebase.

Carica la chiave di autenticazione del servizio APN per l'assistenza Apple

Carica la chiave di autenticazione del servizio APN su Firebase. Se non hai ancora una chiave di autenticazione APN, assicurati di crearne una nel Centro per gli sviluppatori Apple.

  1. All'interno del progetto nella console Firebase, seleziona l'icona a forma di ingranaggio, seleziona Impostazioni progetto e poi la scheda Cloud Messaging.

  2. In Chiave di autenticazione del servizio APN in Configurazione app per iOS, fai clic sul pulsante Carica.

  3. Vai alla posizione in cui hai salvato la chiave, selezionala e fai clic su Apri. Aggiungi l'ID chiave per la chiave (disponibile nel Centro membri Apple Developer) e fai clic su Carica.

Attivare le notifiche push sulle piattaforme Apple

Passaggio 1: aggiungi il framework di notifiche per gli utenti

  1. Fai clic sul progetto in Xcode, quindi seleziona la scheda Generale dall'area Editor.

  2. Scorri verso il basso fino a Framework e librerie collegate e poi fai clic sul pulsante + per aggiungere un framework.

  3. Nella finestra visualizzata, scorri fino a Usernotifications.framework, fai clic sulla voce e quindi su Aggiungi.

Passaggio 2: attiva le notifiche push

  1. Fai clic sul progetto in Xcode, poi seleziona la scheda Funzionalità dall'area di modifica.

  2. Imposta Notifiche push su On.

  3. Scorri verso il basso fino a Modalità background, quindi imposta l'opzione su On.

  4. Seleziona la casella di controllo Notifiche remote in Modalità background.

Inizializza Firebase Cloud Messaging

La libreria Firebase Cloud Messaging verrà inizializzata quando aggiungi gestori per gli eventi TokenReceived o MessageReceived.

All'inizializzazione, viene richiesto un token di registrazione per l'istanza dell'app client. L'app riceverà il token con l'evento OnTokenReceived, che dovrebbe essere memorizzato nella cache per un utilizzo successivo. Ti servirà questo token se vuoi scegliere come target questo dispositivo specifico per i messaggi.

Inoltre, dovrai registrarti per l'evento OnMessageReceived se vuoi poter ricevere messaggi in arrivo.

L'intera configurazione ha il seguente aspetto:

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

Configurazione di un'attività entry point Android

Su Android, Firebase Cloud Messaging è fornito in bundle con un'attività di punto di contatto personalizzato che sostituisce UnityPlayerActivity predefinito. Se non utilizzi un punto di contatto personalizzato, la sostituzione avviene automaticamente e non devi intraprendere alcuna azione aggiuntiva. Le app che non utilizzano l'Attività del punto di ingresso predefinito o che forniscono il proprio Assets/Plugins/AndroidManifest.xml avranno bisogno di una configurazione aggiuntiva.

Il Firebase Cloud Messaging plug-in Unity su Android è fornito in bundle con due file aggiuntivi:

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar contiene un'attività chiamata MessagingUnityPlayerActivity che sostituisce UnityPlayerActivity standard.
  • Assets/Plugins/Android/AndroidManifest.xml indica all'app di utilizzare MessagingUnityPlayerActivity come punto di contatto dell'app.

Questi file vengono forniti perché UnityPlayerActivity predefinito non gestisse le transizioni del ciclo di vita delle attività onStop e onRestart o non implementava onNewIntent, necessario per consentire a Firebase Cloud Messaging di gestire correttamente i messaggi in arrivo.

Configurazione di un'attività punto di ingresso personalizzato

Se la tua app non utilizza il valore UnityPlayerActivity predefinito, dovrai rimuovere il valore AndroidManifest.xml fornito e assicurarti che l'attività personalizzata gestisca correttamente tutte le transizioni del ciclo di vita dell'attività Android (di seguito è riportato un esempio di come eseguire questa operazione). Se la tua attività personalizzata estende UnityPlayerActivity, puoi invece estendere com.google.firebase.MessagingUnityPlayerActivity che implementa tutti i metodi necessari.

Se utilizzi un'attività personalizzata e non espandi com.google.firebase.MessagingUnityPlayerActivity, devi includere i seguenti snippet nella tua attività.

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

Le nuove versioni dell'SDK Firebase C++ (dalla 7.1.0 in poi) utilizzano JobIntentService, che richiede modifiche aggiuntive nel file AndroidManifest.xml.

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

Nota sulla consegna dei messaggi su Android

Quando l'app non è in esecuzione e un utente tocca una notifica, per impostazione predefinita il messaggio non viene inoltrato tramite i callback integrati di FCM. In questo caso, i payload dei messaggi vengono ricevuti tramite un Intent utilizzato per avviare l'applicazione.

I messaggi ricevuti mentre l'app è in background mostrano i contenuti del campo di notifica utilizzato per compilare la notifica nella barra delle applicazioni, ma questo contenuto non verrà comunicato a FCM. In altre parole, FirebaseMessage.Notification sarà un valore nullo.

In sintesi:

Stato dell'app Notifica Dati Entrambe
Primo piano Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
Contesto Barra delle applicazioni Firebase.Messaging.FirebaseMessaging.MessageReceived Notifica: riquadro delle app
Dati: negli extra dell'intent.

Impedire l'inizializzazione automatica

FCM genera un token di registrazione per il targeting per dispositivo. Quando viene generato un token, la libreria carica su Firebase i dati di configurazione e l'identificatore. Se vuoi ottenere un'attivazione esplicita prima di utilizzare il token, puoi impedirne la generazione al momento della configurazione disattivando FCM (e Analytics su Android). Per farlo, aggiungi un valore dei metadati al tuo Info.plist (non al tuo GoogleService-Info.plist) su Apple o al tuo AndroidManifest.xml su 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>

Swift

FirebaseMessagingAutoInitEnabled = NO

Per riattivare FCM, puoi effettuare una chiamata di runtime:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Una volta impostato, questo valore rimane invariato dopo i riavvii dell'app.

FCM consente di inviare messaggi contenenti un link diretto alla tua app. Per ricevere messaggi contenenti un link diretto, devi aggiungere un nuovo filtro per intent all'attività che gestisce i link diretti per la tua app. Il filtro per intent deve rilevare i link diretti del tuo dominio. Se i tuoi messaggi non contengono un link diretto, questa configurazione non è necessaria. Nel file 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>

È anche possibile specificare un carattere jolly per rendere più flessibile il filtro per intent. Ad esempio:

<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 gli utenti toccano una notifica contenente un link allo schema e all'host specificati, la tua app avvia l'attività con questo filtro per intent per gestire il link.

Passaggi successivi

Dopo aver configurato l'app client, puoi inviare messaggi downstream e sull'argomento con Firebase. Per ulteriori informazioni, vedi l'esempio della guida rapida che dimostra questa funzionalità.

Per aggiungere altri comportamenti più avanzati alla tua app, consulta le guide per l'invio di messaggi da un server app:

Tieni presente che per utilizzare queste funzionalità è necessaria un'implementazione del server.