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

Prima di iniziare

Prerequisiti

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

• (Solo piattaforme Apple) Installare quanto segue:

  • Xcode 13.3.1 o versione successiva
  • CocoaPods 1.10.0 o successiva

• Assicurati che il tuo progetto Unity soddisfi questi requisiti:

  • Per iOS : è destinato a iOS 11 o versioni successive
  • Per tvOS : è destinato a tvOS 12 o versioni successive
  • Per Android : ha come target il livello API 19 (KitKat) o superiore

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

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

    • Ottieni una chiave di autenticazione delle notifiche 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.

• Accedi a Firebase utilizzando il tuo account Google.

Se non disponi già di 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 ulteriori informazioni 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 ( plat_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 destinazione di build del tuo progetto Unity desideri 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 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 vengono spesso utilizzati in modo intercambiabile.

   Dove trovi l'ID del tuo progetto Unity?

   Apri il tuo progetto Unity nel tuo IDE Unity, quindi vai alla sezione delle impostazioni per ciascuna piattaforma:

   • Per iOS : vai a Impostazioni di creazione > iOS .

   • Per Android : vai su Android > Impostazioni lettore > Altre impostazioni .

   L'ID del tuo progetto Unity è il valore dell'identificatore del pacchetto (ID di esempio: com.yourcompany.yourproject ).

5. (Facoltativo) Inserisci i nickname specifici della 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 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 .

   Cosa devi sapere su questo file di configurazione?

   • Il file di configurazione di Firebase contiene identificatori univoci ma non segreti per il tuo progetto. Per ulteriori informazioni su questo file di configurazione, visita Comprendere i progetti Firebase .

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

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

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

3. Tornando alla 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 un posto comodo.

   • Puoi scaricare nuovamente 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 .

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 abilitata

   Aggiungi il pacchetto per Firebase Cloud Messaging: FirebaseMessaging.unitypackage

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

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

Passaggio 5: conferma i requisiti della versione dei servizi 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 seguente codice all'inizio della tua applicazione. Puoi verificare e facoltativamente aggiornare i servizi Google Play alla versione richiesta dall'SDK Firebase Unity 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.

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

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

Passaggio 2: attiva le notifiche push

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

2. Imposta Notifiche push su Attivato .

3. Scorri verso il basso fino a Modalità sfondo , quindi impostala su Attiva .

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

Inizializza Firebase Cloud Messaging

La libreria Firebase Cloud Message 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 desideri indirizzare i messaggi a questo dispositivo specifico.

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

L'intera configurazione è simile a questa:

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 l' UnityPlayerActivity predefinita. Se non utilizzi 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à chiamata MessagingUnityPlayerActivity che sostituisce UnityPlayerActivity standard.
• Assets/Plugins/Android/AndroidManifest.xml indica all'app di utilizzare MessagingUnityPlayerActivity come punto di ingresso dell'app.

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

Configurazione di un'attività del punto di ingresso personalizzata

Se la tua app non utilizza UnityPlayerActivity predefinita, dovrai rimuovere il AndroidManifest.xml fornito e assicurarti che l'attività personalizzata gestisca correttamente tutte le transizioni del ciclo di vita dell'attività Android (un esempio di come eseguire questa operazione è mostrato di seguito). 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 , 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 è in esecuzione e un utente tocca una notifica, il messaggio, per impostazione predefinita, non viene 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 campo di notifica utilizzato per popolare la notifica nella barra delle applicazioni, ma il contenuto della notifica non verrà comunicato a FCM. Cioè, FirebaseMessage.Notification sarà nullo.

In sintesi:

Prevenire 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 impedirne 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:

<?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.TokenRegistrationOnInitEnabled = true;

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

Gestione dei messaggi con collegamenti diretti su Android

FCM consente di inviare messaggi contenenti un collegamento diretto alla tua app. Per ricevere messaggi che contengono un collegamento diretto, devi aggiungere un nuovo filtro di intenti all'attività che gestisce i collegamenti diretti per la tua app. Il filtro dell'intento dovrebbe catturare i link diretti del tuo dominio. Se i tuoi messaggi non contengono un collegamento 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 degli intenti. 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 specificato, 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 dimostra questa funzionalità.

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

• Invia messaggi tematici
• Invia a gruppi di dispositivi
• Invia messaggi a monte

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