Inizia a utilizzare Firebase Cloud Messaging nelle app Unity

Questa guida descrive come iniziare a utilizzare Firebase Cloud Messaging nelle tue app client Unity in modo da poter inviare messaggi in modo affidabile.

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 richieste per ogni piattaforma.

Prima di iniziare

Prerequisiti

• Installa Unity 2021 LTS o versioni successive. Anche le versioni precedenti potrebbero essere compatibili, ma non saranno supportate attivamente.

• (Solo piattaforme Apple) Installa quanto segue:

  • Xcode 26.2 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 15 o versioni successive
  • Per tvOS: ha come target tvOS 15 o versioni successive
  • Per Android: deve avere come target il livello API 24 (Nougat) 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 l'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 > Capabilities (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 da connettere al progetto Unity. Consulta Informazioni sui progetti Firebase per scoprire 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 (plat_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 tuo progetto Unity che vuoi registrare oppure puoi anche scegliere di registrare entrambe le destinazioni contemporaneamente.

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

   • Per iOS: inserisci l'ID iOS del tuo progetto Unity nel campo ID pacchetto 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.

   Dove si trova l'ID del progetto Unity?

   Apri il progetto Unity nell'IDE Unity, quindi vai alla sezione delle impostazioni per ogni piattaforma:

   • Per iOS: vai a Impostazioni build > iOS.

   • Per Android: vai a Android > Player Settings > Other Settings.

   L'ID del tuo progetto Unity è il valore Bundle Identifier (ID di esempio: com.yourcompany.yourproject).

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.

   Cosa devi sapere di questo file di configurazione?

   • Il file di configurazione di Firebase contiene identificatori univoci, ma non segreti, per il tuo progetto e la tua app. Per scoprire di più su questo file di configurazione, consulta Informazioni sui progetti Firebase.

   • Puoi scaricare di nuovo il file di configurazione Firebase in qualsiasi momento.

   • Assicurati che al nome del file di configurazione non vengano aggiunti caratteri aggiuntivi, come (2).

2. Apri la finestra Project(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 l'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 ad 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, 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 abilitata

   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. Torna alla console Firebase e, nel flusso di lavoro di configurazione, fai clic su Avanti.

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

Alcuni prodotti nell'SDK Unity Firebase 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 della tua applicazione. Puoi verificare la presenza di Google Play services e, se vuoi, aggiornarlo alla versione richiesta prima di chiamare qualsiasi altro metodo 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 l'utilizzo di Firebase.

Configurare le piattaforme Apple

Per configurare FCM con le piattaforme Unity e Apple, segui queste istruzioni.

Carica la chiave di autenticazione del servizio APN

Carica la chiave di autenticazione del servizio APN su Firebase. Se non hai ancora una chiave di autenticazione APN, assicurati di crearne una nell'Apple Developer Member Center.

1. Nella console Firebase, vai a settings Impostazioni > Generali. Quindi, fai clic sulla scheda Cloud Messaging.
2. In Chiave di autenticazione APN nella sezione Configurazione app per iOS, fai clic su Carica per caricare la chiave di autenticazione di sviluppo, la chiave di autenticazione di produzione o entrambe. È obbligatorio indicarne almeno uno.
3. Sfoglia fino alla posizione in cui hai salvato la chiave, selezionala e fai clic su Apri. Aggiungi l'ID chiave per la chiave (disponibile nel Member Center di Apple Developer) e fai clic su Carica.

Attivare le notifiche push sulle piattaforme Apple

1. Fai clic sul tuo progetto in Xcode, poi seleziona la scheda Generale dall'area Editor.
2. Scorri fino a Linked Frameworks and Libraries (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, quindi fai clic su Aggiungi.
4. Fai clic sul progetto in Xcode, quindi seleziona la scheda Capabilities (Funzionalità) nell'Editor area (Area editor).
5. Imposta Notifiche push su On.
6. Scorri fino a Modalità in background, quindi attiva l'opzione.
7. Seleziona la casella di controllo Notifiche remote in Modalità in background.

Inizializza Firebase Cloud Messaging

Attivare la registrazione utilizzando l'ID installazione Firebase

Per attivare la registrazione dell'istanza dell'app con Firebase Cloud Messaging utilizzando l'ID installazione di Firebase (FID), devi prima attivare i FID nella configurazione dell'app per le piattaforme Android e Apple:

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

FirebaseMessagingInstallationIdEnabled = YES

Registrati agli eventi FCM

La libreria Firebase Cloud Messaging verrà inizializzata quando vengono aggiunti gestori per gli eventi RegistrationReceived o MessageReceived.

All'inizializzazione, Firebase Cloud Messaging registra l'istanza dell'app client per la ricezione di messaggi utilizzando l'ID installazione di Firebase (FID). L'app riceve l'ID istanza app con l'evento RegistrationReceived, che devi memorizzare nella cache sul server per scegliere come target questo dispositivo specifico per i messaggi.

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

La configurazione sarà simile alla seguente:

public void Start() {
  Firebase.Messaging.FirebaseMessaging.RegistrationReceived +=
      OnRegistrationReceived;
  Firebase.Messaging.FirebaseMessaging.MessageReceived +=
      OnMessageReceived;
}

public void OnRegistrationReceived(
    object sender,
    Firebase.Messaging.RegistrationReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received Firebase Installation ID: " +
                        e.InstallationId);
  // TODO: Send the Firebase Installation ID (FID) to your app server to target
  // this device for messages.
}

public void OnMessageReceived(
    object sender,
    Firebase.Messaging.MessageReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received a new message from: " + e.Message.From);
}

Dopo aver ottenuto l'ID installazione di Firebase, invialo al server dell'app e memorizzalo utilizzando il metodo che preferisci.

Registra manualmente quando l'inizializzazione automatica è disattivata

Puoi anche attivare manualmente la registrazione con FCM in fase di runtime utilizzando RegisterAsync():

// Manually register with FCM
Firebase.Messaging.FirebaseMessaging.RegisterAsync().ContinueWith(task => {
  if (task.IsCompleted) {
    // Note: The registered Installation ID is delivered to the
    // RegistrationReceived event handler.
    UnityEngine.Debug.Log("Registered with FCM");
  }
});

Accedi al token di registrazione FCM (deprecato)

Se la tua app utilizza ancora le API dei token deprecate, puoi ascoltare TokenReceived:

// Deprecated: Use RegistrationReceived instead
public void Start() {
  Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
}

public void OnTokenReceived(
    object sender,
    Firebase.Messaging.TokenReceivedEventArgs token) {
  UnityEngine.Debug.Log("Received Registration Token: " + token.Token);
}

Configura con le piattaforme Android

Segui queste istruzioni per configurare FCM con le piattaforme Unity e Android.

Configura un'attività entry point Android

Firebase Cloud Messaging viene fornito con un'attività del punto di accesso personalizzata che sostituisce l'attività predefinita UnityPlayerActivity. Se non utilizzi un punto di accesso personalizzato, questa sostituzione avviene automaticamente e non dovresti dover intraprendere ulteriori azioni.

Il plug-in Unity Firebase Cloud Messaging su Android viene fornito 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é l'elemento UnityPlayerActivity predefinito non gestisce le transizioni del ciclo di vita dell'attività onStop, onRestart né implementa l'elemento onNewIntent necessario per consentire all'elemento Firebase Cloud Messaging di gestire correttamente i messaggi in arrivo.

Configura un'attività con un punto di accesso personalizzato

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 earlier 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 makes sure 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="false" >
</service>

Consegna messaggi su Android

Quando l'app non è in esecuzione e un utente tocca una notifica, per impostazione predefinita il messaggio non viene indirizzato 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 compilare la notifica della barra delle applicazioni, ma i contenuti della notifica non verranno comunicati a FCM. Ciò significa che FirebaseMessage.Notification sarà un valore null.

In sintesi:

Gestione dei messaggi con link diretti su Android

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 intercettare i link diretti del tuo dominio. 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 il filtro per intent più flessibile. 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.

Impedisci l'inizializzazione automatica

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

FirebaseMessagingAutoInitEnabled = NO

Per riattivare FCM, puoi effettuare una chiamata di runtime:

Firebase.Messaging.FirebaseMessaging.RegistrationOnInitEnabled = true;

Una volta impostato, questo valore viene mantenuto anche dopo il riavvio dell'app.

Passaggi successivi

Dopo aver completato i passaggi di configurazione, ecco alcune opzioni per procedere con FCM per Unity:

• Inviare messaggi ai dispositivi
• Ricevi messaggi in un client Unity
• Invia messaggi relativi agli argomenti