Configurare un'app client Firebase Cloud Messaging con Unity

Per scrivere l'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 richieste per ogni piattaforma.

Prima di iniziare

Prerequisiti

  • Installa Unity 2021 LTS o versioni successive. Il supporto di 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 tuo progetto Unity soddisfi questi requisiti:

    • Per iOS: ha come target iOS 13 o versioni successive
    • Per tvOS: ha come 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 queste attività:

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

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

Se non hai ancora un progetto Unity e vuoi solo provare un prodotto Firebase, puoi scaricare uno dei nostri esempi di avvio rapido.

Passaggio 1: crea un progetto Firebase

Prima di poter aggiungere Firebase al tuo progetto Unity, devi creare un progetto Firebase a cui connetterti. Visita la pagina Informazioni sui progetti Firebase per saperne di più sui progetti Firebase.

Passaggio 2: registra la tua app con Firebase

Puoi registrare una o più app o giochi da connettere 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 della 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 progetto Unity che vuoi registrare oppure puoi selezionare la registrazione di entrambe le destinazioni contemporaneamente.

  4. Inserisci gli ID specifici per la piattaforma del tuo progetto Unity.

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

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

  5. (Facoltativo) Inserisci i nickname specifici per la piattaforma del tuo progetto Unity.
    Questi nickname sono identificatori interni e pratici e sono visibili solo a te 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 per la piattaforma nel flusso di lavoro di configurazione della console Firebase.

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

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

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

  3. Nella console Firebase, 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 Firebase Unity SDK, 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 Assets > Import Package > Custom Package (Risorse > 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, nell'ambito della 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 abilitato

    Aggiungi il pacchetto per Firebase Cloud Messaging: FirebaseMessaging.unitypackage

  4. Nella finestra Import Unity Package (Importa il pacchetto Unity), fai clic su Import (Importa).

  5. Nella console Firebase, nel flusso di lavoro di configurazione, fai clic su Avanti.

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

Alcuni prodotti dell'SDK Firebase Unity per Android richiedono Google Play services. Scopri quali prodotti hanno questa dipendenza. Google Play services deve essere aggiornato prima di poter utilizzare questi prodotti.

Aggiungi la seguente istruzione using e il codice di inizializzazione all'inizio dell'applicazione. Puoi controllare e, se vuoi, aggiornare Google Play services alla versione richiesta 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 tuo progetto Unity è registrato e configurato per utilizzare 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 APNs, assicurati di crearne una nel Centro membri 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 APN nella sezione Configurazione app iOS, fai clic sul pulsante Carica.

  3. Sfoglia fino alla posizione in cui hai salvato la chiave, selezionala e fai clic su Apri. Aggiungi l'ID chiave (disponibile nel Developer Member Center di Apple) e fai clic su Carica.

Attivare le notifiche push sulle piattaforme Apple

Passaggio 1: aggiungi il framework delle notifiche utente

  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 collegati, poi fai clic sul pulsante + per aggiungere un framework.

  3. Nella finestra visualizzata, scorri fino a UserNotifications.framework, fai clic su questa voce e poi su Aggiungi.

Passaggio 2: attiva le notifiche push

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

  2. Imposta l'opzione Notifiche push su On.

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

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

Inizializza Firebase Cloud Messaging

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

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

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

L'intera configurazione ha questo 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à di entry point Android

Su Android, Firebase Cloud Messaging viene fornito in bundle con un'attività di punto di ingresso personalizzato che sostituisce l'attività UnityPlayerActivity predefinita. Se non utilizzi un punto di accesso personalizzato, questa sostituzione avviene automaticamente e non devi intraprendere ulteriori azioni. Le app che non utilizzano l'attività punto di ingresso predefinita o che forniscono il proprio Assets/Plugins/AndroidManifest.xml richiedono una configurazione aggiuntiva.

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

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

Questi file vengono forniti perché UnityPlayerActivity predefinito non gestisce le transizioni del ciclo di vita dell'attività onStop, onRestart o implementa onNewIntent, necessario per Firebase Cloud Messaging per gestire correttamente i messaggi in arrivo.

Configurazione di un'attività di punto di ingresso personalizzata

Se la tua app non utilizza UnityPlayerActivity predefinito, dovrai rimuovere AndroidManifest.xml fornito e assicurarti che la tua attività personalizzata gestisca correttamente tutte le transizioni del ciclo di vita dell'attività Android (di seguito è riportato un esempio di come farlo). 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 estendi com.google.firebase.MessagingUnityPlayerActivity, devi includere i seguenti snippet nell'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++ (7.1.0 e successive) 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="true" >
</service>

Nota sulla consegna dei messaggi su Android

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

I messaggi ricevuti mentre l'app è in background utilizzano il contenuto del campo di notifica per popolare la notifica della barra delle applicazioni, ma il contenuto della notifica non verrà comunicato a FCM. ovvero 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: barra delle notifiche
Dati: negli extra dell'intent.

Impedisci l'inizializzazione automatica

FCM genera un token di registrazione per il targeting dei dispositivi. Quando viene generato un token, la libreria carica l'identificatore e i dati di configurazione su Firebase. Se vuoi ottenere un consenso esplicito prima di utilizzare il token, puoi impedire la generazione al momento della configurazione disattivando FCM (e su Android, Analytics). 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 viene mantenuto anche dopo il riavvio dell'app.

FCM consente l'invio di 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 intercettare i link diretti del tuo dominio. Se i tuoi messaggi non contengono un link diretto, questa configurazione non è necessaria. In 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 che specifichi, 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 per argomento con Firebase. Per saperne di più, consulta l'esempio di avvio rapido che illustra 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 lato server.