Configura un'app client Firebase Cloud Messaging con Unity

Per scrivere la tua app client multipiattaforma Firebase Cloud Messaging con Unity, utilizza l'API Firebase Cloud Messaging . Unity SDK funziona sia per Android che per Apple, con alcune configurazioni aggiuntive richieste 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 obsoleto e non sarà più supportato attivamente dopo la prossima versione principale.

• (Solo piattaforme Apple) Installa quanto segue:

  • Xcode 13.3.1 o successivo
  • CocoaPods 1.10.0 o superiore

• Assicurati che il tuo progetto Unity soddisfi questi requisiti:

  • Per iOS : ha come target iOS 11 o versioni successive
  • Per tvOS : target tvOS 12 o versioni successive
  • Per Android : mira al 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 per le 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 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 per connetterti al tuo progetto Unity. Visita Capire 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 di Firebase .

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

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

3. Seleziona l'obiettivo di compilazione del tuo progetto Unity che desideri registrare oppure puoi anche scegliere di registrare entrambi gli obiettivi 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 pacchetto 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.

   Dove trovi l'ID del tuo progetto Unity?

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

   • Per iOS : passa a Impostazioni build > iOS .

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

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

5. (Facoltativo) Inserisci i soprannomi specifici della piattaforma del tuo progetto Unity.
   Questi nickname sono identificatori di convenienza interni e sono visibili solo a te nella console di 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 Understand Firebase Projects .

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

   • Assicurati che il nome del file di configurazione non sia aggiunto con caratteri aggiuntivi, come (2) .

2. Apri la finestra Progetto del 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 di Firebase, fai clic su Scarica Firebase Unity SDK , quindi decomprimi l'SDK in un punto comodo.

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

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

2. Nel 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 , fai 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 di Google Play

L'SDK Firebase Unity per Android richiede Google Play Services , che deve essere aggiornato prima di poter utilizzare l'SDK.

Aggiungere il codice seguente all'inizio dell'applicazione. Puoi verificare e facoltativamente aggiornare Google Play Services alla versione richiesta dall'SDK Firebase Unity prima di chiamare altri metodi 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: aggiungere il framework delle notifiche utente

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 visualizzata, scorri fino a UserNotifications.framework , fai clic su tale voce, quindi fai clic su Aggiungi .

Passaggio 2: abilita le notifiche push

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

2. Imposta Notifiche push su On .

3. Scorri verso il basso fino a Modalità in background , quindi impostalo su On .

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, sarà necessario registrarsi all'evento OnMessageReceived se si desidera 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 predefinito. Se non utilizzi un punto di ingresso personalizzato, questa sostituzione avviene automaticamente e non dovresti intraprendere alcuna azione aggiuntiva. Le app che non usano 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 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é l' UnityPlayerActivity predefinito non gestisce le transizioni del ciclo di vita delle attività onStop , onRestart o implementa onNewIntent che è necessario affinché Firebase Cloud Messaging gestisca correttamente i messaggi in arrivo.

Configurazione di un punto di ingresso personalizzato Activity

Se la tua app non usa l' UnityPlayerActivity predefinito, 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 , 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 di Firebase C++ SDK (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>

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 attraverso i callback incorporati 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 loro campo di notifica utilizzato per popolare la notifica della barra delle applicazioni, ma tale contenuto della notifica non verrà comunicato a FCM. Cioè, FirebaseMessage.Notification sarà nullo.

In sintesi:

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 in Firebase. Se desideri ottenere un consenso esplicito prima di utilizzare il token, puoi impedire la generazione al momento della 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 deep link su Android

FCM consente l'invio di messaggi contenenti un collegamento diretto alla tua app. Per ricevere messaggi che contengono un collegamento diretto, devi aggiungere un nuovo filtro intent all'attività che gestisce i collegamenti diretti per la tua app. Il filtro intent dovrebbe catturare i link diretti del tuo dominio. Se i tuoi messaggi non contengono un collegamento 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 intent. 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 intent per gestire il collegamento.

Prossimi passi

Dopo aver configurato l'app client, sei pronto per inviare messaggi downstream e topic 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 di argomento
• Invia a gruppi di dispositivi
• Invia messaggi a monte

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