Configurer une application client Firebase Cloud Messaging avec Unity

Pour écrire votre application client multiplateforme Firebase Cloud Messaging avec Unity, utilisez l'API Firebase Cloud Messaging . Le SDK Unity fonctionne à la fois pour Android et Apple, avec une configuration supplémentaire requise pour chaque plate-forme.

Avant que tu commences

Conditions préalables

• Installez Unity 2019.1 ou version ultérieure. Les versions antérieures peuvent également être compatibles mais ne seront pas activement prises en charge. La prise en charge de Unity 2019.1 est considérée comme obsolète et ne sera plus activement prise en charge après la prochaine version majeure.

• (Plateformes Apple uniquement) Installez les éléments suivants :

  • Xcode 13.3.1 ou supérieur
  • CocoaPods 1.10.0 ou supérieur

• Assurez-vous que votre projet Unity répond aux exigences suivantes :

  • Pour iOS — cible iOS 11 ou supérieur
  • Pour tvOS - cible tvOS 12 ou supérieur
  • Pour Android - cible le niveau d'API 19 (KitKat) ou supérieur

• Configurez un appareil ou utilisez un émulateur pour exécuter votre projet Unity.

  • Pour iOS ou tvOS — Configurez un appareil physique pour exécuter votre application et effectuez ces tâches :

    • Obtenez une clé d'authentification Apple Push Notification pour votre compte développeur Apple .
    • Activez les notifications push dans XCode sous App > Capabilities .

  • Pour Android — Les émulateurs doivent utiliser une image d'émulateur avec Google Play.

• Connectez-vous à Firebase à l'aide de votre compte Google.

Si vous n'avez pas encore de projet Unity et que vous souhaitez simplement essayer un produit Firebase, vous pouvez télécharger l'un de nos exemples de démarrage rapide .

Étape 1 : Créer un projet Firebase

Avant de pouvoir ajouter Firebase à votre projet Unity, vous devez créer un projet Firebase pour vous connecter à votre projet Unity. Consultez Comprendre les projets Firebase pour en savoir plus sur les projets Firebase.

Étape 2 : Enregistrez votre application auprès de Firebase

Vous pouvez enregistrer une ou plusieurs applications ou jeux pour vous connecter à votre projet Firebase.

1. Accédez à la console Firebase .

2. Au centre de la page de présentation du projet, cliquez sur l'icône Unity ( plat_unity ) pour lancer le workflow de configuration.

   Si vous avez déjà ajouté une application à votre projet Firebase, cliquez sur Ajouter une application pour afficher les options de plate-forme.

3. Sélectionnez la cible de construction de votre projet Unity que vous souhaitez enregistrer, ou vous pouvez même choisir d'enregistrer les deux cibles maintenant en même temps.

4. Saisissez le ou les identifiants spécifiques à la plate-forme de votre projet Unity.

   • Pour iOS — Saisissez l'ID iOS de votre projet Unity dans le champ ID du bundle iOS .

   • Pour Android — Entrez l'ID Android de votre projet Unity dans le champ du nom du package Android .
     Les termes nom de package et ID d'application sont souvent utilisés de manière interchangeable.

   Où trouvez-vous l'ID de votre projet Unity ?

   Ouvrez votre projet Unity dans votre IDE Unity, puis accédez à la section des paramètres pour chaque plate-forme :

   • Pour iOS — Naviguez vers Build Settings > iOS .

   • Pour Android — Accédez à Android > Paramètres du lecteur > Autres paramètres .

   L'ID de votre projet Unity est la valeur de l'identifiant du bundle (exemple d'ID : com.yourcompany.yourproject ).

5. (Facultatif) Entrez le ou les surnoms spécifiques à la plate-forme de votre projet Unity.
   Ces surnoms sont des identifiants internes de commodité et ne sont visibles que par vous dans la console Firebase.

6. Cliquez sur Enregistrer l'application .

Étape 3 : Ajouter des fichiers de configuration Firebase

1. Obtenez vos fichiers de configuration Firebase spécifiques à la plate-forme dans le flux de travail de configuration de la console Firebase.

   • Pour iOS — Cliquez sur Télécharger GoogleService-Info.plist .

   • Pour Android — Cliquez sur Télécharger google-services.json .

   Que devez-vous savoir sur ce fichier de configuration ?

   • Le fichier de configuration Firebase contient des identifiants uniques mais non secrets pour votre projet. Pour en savoir plus sur ce fichier de configuration, consultez Comprendre les projets Firebase .

   • Vous pouvez télécharger à nouveau votre fichier de configuration Firebase à tout moment.

   • Assurez-vous que le nom du fichier de configuration n'est pas ajouté avec des caractères supplémentaires, comme (2) .

2. Ouvrez la fenêtre Projet de votre projet Unity, puis déplacez vos fichiers de configuration dans le dossier Assets .

3. De retour dans la console Firebase, dans le workflow de configuration, cliquez sur Suivant .

Étape 4 : Ajouter des SDK Firebase Unity

1. Dans la console Firebase, cliquez sur Télécharger le SDK Firebase Unity , puis décompressez le SDK à un endroit pratique.

   • Vous pouvez télécharger à nouveau le SDK Firebase Unity à tout moment.

   • Le SDK Firebase Unity n'est pas spécifique à la plate-forme.

2. Dans votre projet Unity ouvert, accédez à Assets > Import Package > Custom Package .

3. Dans le SDK décompressé, sélectionnez les produits Firebase pris en charge que vous souhaitez utiliser dans votre application.

   Pour une expérience optimale avec Firebase Cloud Messaging, nous vous recommandons d'activer Google Analytics dans votre projet. De plus, dans le cadre de la configuration d'Analytics, vous devez ajouter le package Firebase pour Analytics à votre application.

   Analyse activée

   • Ajoutez le package Firebase pour Google Analytics : FirebaseAnalytics.unitypackage
   • Ajoutez le package pour Firebase Cloud Messaging : FirebaseMessaging.unitypackage

   Analyse non activée

   Ajoutez le package pour Firebase Cloud Messaging : FirebaseMessaging.unitypackage

4. Dans la fenêtre Importer un package Unity , cliquez sur Importer .

5. De retour dans la console Firebase, dans le workflow de configuration, cliquez sur Suivant .

Étape 5 : Confirmez la configuration requise pour la version des services Google Play

Le SDK Firebase Unity pour Android nécessite les services Google Play , qui doivent être à jour avant que le SDK puisse être utilisé.

Ajoutez le code suivant au début de votre application. Vous pouvez rechercher et éventuellement mettre à jour les services Google Play vers la version requise par le SDK Firebase Unity avant d'appeler toute autre méthode dans le 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.
  }
});

Votre projet Unity est enregistré et configuré pour utiliser Firebase.

Activer les notifications push sur les plates-formes Apple

Étape 1 : Ajouter un cadre de notifications utilisateur

1. Cliquez sur le projet dans Xcode, puis sélectionnez l'onglet Général dans la zone Éditeur .

2. Faites défiler jusqu'à Linked Frameworks and Libraries , puis cliquez sur le bouton + pour ajouter un framework.

3. Dans la fenêtre qui apparaît, faites défiler jusqu'à UserNotifications.framework , cliquez sur cette entrée, puis cliquez sur Ajouter .

Étape 2 : Activer les notifications push

1. Cliquez sur le projet dans Xcode, puis sélectionnez l'onglet Capacités dans la zone Éditeur .

2. Basculez les notifications push sur Activé .

3. Faites défiler jusqu'à Modes d'arrière-plan , puis réglez-le sur Activé .

4. Cochez la case Notifications à distance sous Modes d'arrière-plan .

Initialiser Firebase Cloud Messaging

La bibliothèque Firebase Cloud Message sera initialisée lors de l'ajout de gestionnaires pour les événements TokenReceived ou MessageReceived .

Lors de l'initialisation, un jeton d'enregistrement est demandé pour l'instance d'application cliente. L'application recevra le jeton avec l'événement OnTokenReceived , qui doit être mis en cache pour une utilisation ultérieure. Vous aurez besoin de ce jeton si vous souhaitez cibler cet appareil spécifique pour les messages.

De plus, vous devrez vous inscrire à l'événement OnMessageReceived si vous souhaitez pouvoir recevoir des messages entrants.

L'ensemble de la configuration ressemble à ceci :

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);
}

Configuration d'une activité de point d'entrée Android

Sur Android, Firebase Cloud Messaging est fourni avec une activité de point d'entrée personnalisée qui remplace la valeur par défaut UnityPlayerActivity . Si vous n'utilisez pas de point d'entrée personnalisé, ce remplacement se produit automatiquement et vous ne devriez pas avoir à effectuer d'action supplémentaire. Les applications qui n'utilisent pas l'Activité de point d'entrée par défaut ou qui fournissent leurs propres Assets/Plugins/AndroidManifest.xml auront besoin d'une configuration supplémentaire.

Le plug-in Firebase Cloud Messaging Unity sur Android est fourni avec deux fichiers supplémentaires :

• Assets/Plugins/Android/libmessaging_unity_player_activity.jar contient une activité appelée MessagingUnityPlayerActivity qui remplace la norme UnityPlayerActivity .
• Assets/Plugins/Android/AndroidManifest.xml indique à l'application d'utiliser MessagingUnityPlayerActivity comme point d'entrée de l'application.

Ces fichiers sont fournis car la valeur par défaut UnityPlayerActivity ne gère pas les transitions du cycle de vie des activités onStop , onRestart ou n'implémente pas onNewIntent qui est nécessaire pour que Firebase Cloud Messaging gère correctement les messages entrants.

Configuration d'une activité de point d'entrée personnalisée

Si votre application n'utilise pas l' UnityPlayerActivity par défaut, vous devrez supprimer le AndroidManifest.xml fourni et vous assurer que votre activité personnalisée gère correctement toutes les transitions du cycle de vie de l'activité Android (un exemple de la manière de procéder est illustré ci-dessous). Si votre activité personnalisée étend UnityPlayerActivity vous pouvez à la place étendre com.google.firebase.MessagingUnityPlayerActivity qui implémente toutes les méthodes nécessaires.

Si vous utilisez une activité personnalisée et que vous n'étendez pas com.google.firebase.MessagingUnityPlayerActivity , vous devez inclure les extraits suivants dans votre activité.

/**
 * 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);
}

Les nouvelles versions de Firebase C++ SDK (à partir de la version 7.1.0) utilisent JobIntentService qui nécessite des modifications supplémentaires dans le fichier AndroidManifest.xml .

<service android:name="com.google.firebase.messaging.MessageForwardingService"
     android:permission="android.permission.BIND_JOB_SERVICE"
     android:exported="false" >
</service>

Remarque sur la livraison des messages sur Android

Lorsque l'application ne fonctionne pas du tout et qu'un utilisateur appuie sur une notification, le message n'est pas, par défaut, acheminé via les rappels intégrés de FCM. Dans ce cas, les charges utiles de message sont reçues via une Intent utilisée pour démarrer l'application.

Les messages reçus lorsque l'application est en arrière-plan ont le contenu de leur champ de notification utilisé pour remplir la notification de la barre d'état système, mais ce contenu de notification ne sera pas communiqué à FCM. Autrement dit, FirebaseMessage.Notification sera nul.

En résumé:

Empêcher l'initialisation automatique

FCM génère un jeton d'enregistrement pour le ciblage par appareil. Lorsqu'un jeton est généré, la bibliothèque télécharge l'identifiant et les données de configuration sur Firebase. Si vous souhaitez obtenir un opt-in explicite avant d'utiliser le jeton, vous pouvez empêcher la génération au moment de la configuration en désactivant FCM (et sur Android, Analytics). Pour ce faire, ajoutez une valeur de métadonnées à votre Info.plist (et non à votre GoogleService-Info.plist ) sur Apple ou à votre AndroidManifest.xml sur 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

Pour réactiver FCM, vous pouvez effectuer un appel d'exécution :

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Cette valeur persiste lors des redémarrages de l'application une fois définie.

Gestion des messages avec des liens profonds sur Android

FCM permet d'envoyer des messages contenant un lien profond vers votre application. Pour recevoir des messages contenant un lien profond, vous devez ajouter un nouveau filtre d'intention à l'activité qui gère les liens profonds pour votre application. Le filtre d'intention doit capturer les liens profonds de votre domaine. Si vos messages ne contiennent pas de lien profond, cette configuration n'est pas nécessaire. Dans 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>

Il est également possible de spécifier un caractère générique pour rendre le filtre d'intention plus flexible. Par exemple:

<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>

Lorsque les utilisateurs appuient sur une notification contenant un lien vers le schéma et l'hôte que vous spécifiez, votre application démarre l'activité avec ce filtre d'intention pour gérer le lien.

Prochaines étapes

Après avoir configuré l'application cliente, vous êtes prêt à envoyer des messages en aval et de sujet avec Firebase. Pour en savoir plus, consultez l' exemple de démarrage rapide qui illustre cette fonctionnalité.

Pour ajouter d'autres comportements plus avancés à votre application, consultez les guides d'envoi de messages depuis un serveur d'application :

• Envoyer des messages de sujet
• Envoyer aux groupes d'appareils
• Envoyer des messages en amont

Gardez à l'esprit que vous aurez besoin d'une implémentation de serveur pour utiliser ces fonctionnalités.