Check out what’s new from Firebase at Google I/O 2022. Learn more

Configura 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 impostazioni aggiuntive necessarie per ciascuna piattaforma.

Prima di iniziare

Prerequisiti

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

  • (solo iOS) Installa quanto segue:

    • Xcode 13.3.1 o successivo
    • CocoaPods 1.10.0 o versioni successive
  • Assicurati che il tuo progetto Unity soddisfi questi requisiti:

    • Per iOS : target iOS 10 o versioni successive
    • Per Android : target API livello 19 (KitKat) o superiore

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

    • Per iOS : configura un dispositivo iOS fisico per eseguire la tua app e completa queste attività:

      • Ottieni una chiave di autenticazione di notifica push Apple per il tuo account sviluppatore Apple .
      • Abilita le notifiche push in XCode in App > Funzionalità .
    • Per Android : gli emulatori devono utilizzare un'immagine dell'emulatore con Google Play.

Se non hai già un progetto Unity e desideri semplicemente 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 per connetterti al tuo progetto Unity. Visita Comprendere i 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 per connetterti al tuo progetto Firebase.

  1. Vai alla console Firebase .

  2. Al centro della pagina di panoramica 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 quale build target del tuo progetto Unity desideri registrare, oppure puoi anche selezionare di registrare entrambi i target ora 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 bundle iOS .

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

  5. (Facoltativo) Inserisci i soprannomi specifici della piattaforma del tuo progetto Unity.
    Questi soprannomi sono identificatori di convenienza interni e sono visibili solo a te nella console Firebase.

  6. Fare clic su Registra app .

Passaggio 3: aggiungi i file di configurazione di Firebase

  1. Ottieni i file di configurazione Firebase specifici della 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 tuoi 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 di Firebase Unity

  1. Nella console Firebase, fai clic su Scarica Firebase Unity SDK , quindi decomprimi l'SDK in un punto conveniente.

    • Puoi scaricare nuovamente Firebase Unity SDK in qualsiasi momento.

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

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

  3. Dall'SDK decompresso, seleziona i prodotti Firebase supportati che desideri utilizzare nella tua app.

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

    Analisi abilitata

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

    Analisi non abilitate

    Aggiungi il pacchetto per Firebase Cloud Messaging: FirebaseMessaging.unitypackage

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

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

Passaggio 5: conferma i requisiti della versione dei servizi di Google Play

L'SDK Firebase Unity per Android richiede i servizi Google Play , che devono essere aggiornati prima di poter utilizzare l'SDK.

Aggiungi il codice seguente all'inizio della tua applicazione. Puoi verificare e, facoltativamente, aggiornare i servizi di Google Play alla versione richiesta da Firebase Unity SDK prima di chiamare qualsiasi altro metodo nell'SDK.

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(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.

Passaggio 7: aggiungi il framework per le notifiche degli utenti

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

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

  3. Nella finestra che appare, scorri fino a UserNotifications.framework , fai clic su quella voce, quindi fai clic su Aggiungi .

Passaggio 8: abilita le notifiche push

  1. Fare clic sul progetto in Xcode, quindi selezionare la scheda Funzionalità dall'area Editor .

  2. Attiva le notifiche push .

  3. Scorri verso il basso fino a Modalità sfondo , quindi attivalo .

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

Inizializza Firebase Cloud Messaging

La libreria dei messaggi di Firebase Cloud verrà inizializzata quando si aggiungono 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 dovrebbe essere memorizzato nella cache per un uso successivo. Avrai bisogno di questo token se vuoi indirizzare questo dispositivo specifico per i messaggi.

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

L'intera configurazione si presenta così:

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à del punto di ingresso Android

Su Android, Firebase Cloud Messaging viene fornito in bundle con un'attività del punto di ingresso personalizzata che sostituisce UnityPlayerActivity predefinita. Se non stai utilizzando un punto di ingresso personalizzato, questa sostituzione avviene automaticamente e non dovresti intraprendere alcuna azione aggiuntiva. Le app che non utilizzano l'attività del punto di ingresso predefinito o che forniscono i propri Assets/Plugins/AndroidManifest.xml avranno bisogno di una configurazione aggiuntiva.

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

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar contiene un'attività denominata MessagingUnityPlayerActivity che sostituisce lo standard UnityPlayerActivity .
  • Assets/Plugins/Android/AndroidManifest.xml indica all'app di usare MessagingUnityPlayerActivity come punto di ingresso per l'app.

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

Configurazione di un punto di ingresso personalizzato Attività

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

Se stai utilizzando un'attività personalizzata e non com.google.firebase.MessagingUnityPlayerActivity , dovresti 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 di Firebase C++ SDK (dalla 7.1.0 in poi) utilizzano JobIntentService che richiede ulteriori modifiche 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 è affatto in esecuzione e un utente tocca una notifica, il messaggio non viene, per impostazione predefinita, instradato 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 hanno il contenuto del relativo campo di notifica utilizzato per popolare la notifica della barra delle applicazioni, ma il contenuto della notifica non verrà comunicato a FCM. Cioè, FirebaseMessage.Notification sarà un null.

In sintesi:

Stato dell'app Notifica Dati Tutti e due
Primo piano Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
Sfondo Area di notifica Firebase.Messaging.FirebaseMessaging.MessageReceived Notifica: barra delle applicazioni
Dati: in extra dell'intento.

Impedisci l'inizializzazione automatica

FCM genera un token di registrazione per il targeting del dispositivo. Quando viene generato un token, la libreria carica l'identificatore e i dati di configurazione su Firebase. Se desideri ottenere un consenso esplicito prima di utilizzare il token, puoi impedire la generazione in fase di configurazione disabilitando FCM (e su Android, Analytics). Per fare ciò, aggiungi un valore di metadati al tuo Info.plist (non al tuo GoogleService-Info.plist ) su Apple o al tuo AndroidManifest.xml su 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>

Veloce

FirebaseMessagingAutoInitEnabled = NO

Per riattivare FCM, puoi effettuare una chiamata di runtime:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Questo valore persiste tra i riavvii dell'app una volta impostato.

FCM consente di inviare messaggi contenenti un collegamento diretto alla tua app. Per ricevere messaggi che contengono un link diretto, devi aggiungere un nuovo filtro intento all'attività che gestisce i link diretti per la tua app. Il filtro dell'intento dovrebbe catturare i link diretti del tuo dominio. Se i tuoi messaggi non contengono un deep link, 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 dell'intento. Per 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 collegamento allo schema e all'host specificati, la tua app avvierà l'attività con questo filtro di intenti per gestire il collegamento.

Prossimi passi

Dopo aver configurato l'app client, sei pronto per inviare messaggi downstream e di argomento con Firebase. Per ulteriori informazioni, vedere l' esempio di avvio rapido che illustra questa funzionalità.

Per aggiungere un altro comportamento più avanzato alla tua app, consulta le guide per l'invio di messaggi da un server di app:

Tieni presente che avrai bisogno di un'implementazione del server per utilizzare queste funzionalità.