Ce guide de démarrage rapide explique comment configurer Firebase Cloud Messaging dans vos applications clientes mobiles et Web pour pouvoir envoyer des messages de manière fiable. Pour les environnements serveur, consultez Votre environnement serveur et FCM.

Configurer une application cliente Firebase Cloud Messaging avec Unity

Pour écrire votre application cliente Firebase Cloud Messaging multiplate-forme avec Unity, utilisez l'API Firebase Cloud Messaging. Le SDK Unity fonctionne pour Android et Apple, mais une configuration supplémentaire est requise pour chaque plate-forme.

Avant de commencer

Prérequis

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

• (Plate-formes Apple uniquement) Installez les éléments suivants :

  • Xcode 13.3.1 ou version ultérieure
  • CocoaPods 1.12.0 ou version ultérieure

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

  • Pour iOS : cible iOS 13 ou version ultérieure
  • Pour tvOS : cible tvOS 13 ou version ultérieure
  • Pour Android : cible le niveau d'API 21 (Lollipop) ou version ultérieure

• 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, puis effectuez les tâches suivantes :

    • Obtenez une clé d'authentification Apple Push Notification pour votre compte de 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 avec 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éez 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 les associer à 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 build de votre projet Unity que vous souhaitez enregistrer. Vous pouvez même choisir d'enregistrer les deux cibles en même temps.

4. Saisissez le ou les ID 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 : saisissez l'ID Android de votre projet Unity dans le champ Nom du package Android.
     Les termes nom du package et ID de l'application sont souvent utilisés de manière interchangeable.

   Où trouver 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 : accédez à Build Settings > iOS (Paramètres de compilation > iOS).

   • Pour Android : accédez à Android > Player Settings > Other Settings (Android > Paramètres du lecteur > Autres paramètres).

   L'ID de votre projet Unity correspond à la valeur de l'identifiant de groupe (exemple d'ID : com.yourcompany.yourproject).

5. (Facultatif) Saisissez le ou les noms spécifiques à la plate-forme de votre projet Unity.
   Ces alias sont des identifiants internes pratiques qui ne sont visibles que par vous dans la console Firebase.

6. Cliquez sur Enregistrer l'application.

Étape 3 : Ajoutez les fichiers de configuration Firebase

1. Obtenez vos fichiers de configuration Firebase spécifiques à la plate-forme dans le workflow 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 pas secrets, pour votre projet et votre application. 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.

   • Veillez à ne pas inclure de caractères supplémentaires dans le nom du fichier de configuration, par exemple (2).

2. Ouvrez la fenêtre Project(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 les SDK Firebase Unity

1. Dans la console Firebase, cliquez sur Télécharger le SDK Unity, puis décompressez le SDK à l'emplacement de votre choix.Firebase

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

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

2. Dans votre projet Unity ouvert, accédez à Assets (Éléments) > Import Package (Importer un package) > Custom Package (Package personnalisé).

3. Dans le SDK décompressé, sélectionnez les produits Firebase compatibles 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, lors de la configuration de Analytics, vous devez ajouter le package Firebase pour Analytics à votre application.

   Analytics activé

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

   Analytics non activé

   Ajoutez le package pour Firebase Cloud Messaging : FirebaseMessaging.unitypackage

4. Dans la fenêtre Import Unity Package (Importer un package Unity) qui s'ouvre, cliquez sur Import (Importer).

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

Étape 5 : Vérifiez la version requise des services Google Play

Certains produits du SDK Firebase Unity pour Android nécessitent Google Play services. Découvrez les produits qui présentent cette dépendance. Google Play services doit être à jour pour que vous puissiez utiliser ces produits.

Ajoutez l'instruction using et le code d'initialisation suivants au début de votre application. Vous pouvez vérifier et, si vous le souhaitez, mettre à jour Google Play services vers la version requise avant d'appeler d'autres méthodes dans le 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.
  }
});

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

Configurer les plates-formes Apple

Suivez les instructions ci-dessous pour configurer FCM avec les plates-formes Unity et Apple.

Importer votre clé d'authentification APNs

Importez votre clé d'authentification APNs dans Firebase. Si vous ne possédez pas encore de clé d'authentification APNs, veillez à en créer une dans le Centre des membres Apple Developer.

1. Dans votre projet de la console Firebase, sélectionnez l'icône en forme de roue dentée, puis Paramètres du projet et enfin l'onglet Cloud Messaging.

2. Dans Clé d'authentification APNs sous Configuration de l'application iOS, cliquez sur le bouton Importer pour importer votre clé d'authentification de développement, votre clé d'authentification de production ou les deux. Veuillez inclure au moins une image.

3. Accédez à l'emplacement où vous avez enregistré votre clé, sélectionnez-la, puis cliquez sur Ouvrir. Ajoutez l'ID de la clé (disponible dans l' Apple Developer Member Center), puis cliquez sur Importer.

Activer les notifications push sur les plates-formes Apple

1. Cliquez sur votre projet dans Xcode, puis sélectionnez l'onglet Général dans la zone de l'éditeur.
2. Faites défiler l'écran jusqu'à Linked Frameworks and Libraries (Bibliothèques et frameworks associés), puis cliquez sur le bouton + pour ajouter un framework.
3. Dans la fenêtre qui s'affiche, faites défiler la page jusqu'à UserNotifications.framework, cliquez sur cette entrée, puis sur Ajouter.
4. Cliquez sur votre projet dans Xcode, puis sélectionnez l'onglet Capabilities (Fonctionnalités) dans la zone de l'éditeur.
5. Activez l'option Notifications push.
6. Faites défiler l'écran jusqu'à Modes d'arrière-plan, puis activez l'option.
7. 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 de l'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.

La configuration se présente comme suit :

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

Configurer les plates-formes Android

Suivez les instructions ci-dessous pour configurer FCM avec les plates-formes Unity et Android.

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

Firebase Cloud Messaging est fourni avec une activité de point d'entrée personnalisée qui remplace UnityPlayerActivity par défaut. Si vous n'utilisez pas de point d'entrée personnalisé, ce remplacement se fait automatiquement et vous n'avez aucune action supplémentaire à effectuer.

Le plug-in Unity Firebase Cloud Messaging 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 l'activité UnityPlayerActivity standard.
• Assets/Plugins/Android/AndroidManifest.xml indique à l'application d'utiliser MessagingUnityPlayerActivity comme point d'entrée.

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

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

Si votre application n'utilise pas le 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 procédure à suivre est présenté ci-dessous). Si votre activité personnalisée étend UnityPlayerActivity, vous pouvez étendre com.google.firebase.MessagingUnityPlayerActivity à la place, ce 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 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);
}

Les nouvelles versions du SDK Firebase C++ (7.1.0 et ultérieures) utilisent JobIntentService, ce 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>

Distribution des messages sur Android

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

Le contenu du champ de notification des messages reçus lorsque l'application est en arrière-plan est utilisé pour remplir la notification de la barre d'état système, mais ce contenu de notification ne sera pas communiqué à FCM. Cela signifie que FirebaseMessage.Notification sera nul.

En résumé :

Gérer les 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 filtre d'intent à l'activité qui gère les liens profonds pour votre application. Le filtre d'intent doit intercepter les liens profonds de votre domaine. 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'intent plus flexible. 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'intent pour gérer le lien.

Empêcher l'initialisation automatique

FCM génère un jeton d'enregistrement pour le ciblage des appareils. Lorsqu'un jeton est généré, la bibliothèque importe l'identifiant et les données de configuration dans Firebase. Si vous souhaitez obtenir un consentement explicite avant d'utiliser le jeton, vous pouvez empêcher sa génération lors de la configuration en désactivant FCM (et Analytics sur Android). Vous pouvez ajouter 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;

Une fois définie, cette valeur persiste lors des redémarrages de l'application.

Étapes suivantes

Une fois la configuration terminée, voici quelques options pour aller plus loin avec FCM pour Unity :

• Envoyer des messages thématiques
• Envoyer à des groupes d'appareils