Premiers pas avec Firebase Cloud Messaging dans les applications Flutter

Ce guide explique comment commencer à utiliser Firebase Cloud Messaging dans vos applications clientes Flutter afin de pouvoir envoyer des messages de manière fiable.

Selon la plate-forme cible, vous devrez suivre des étapes de configuration supplémentaires.

iOS+

Swizzling de méthode

Pour utiliser le FCM plug-in Flutter sur les appareils Apple, vous devez effectuer un swizzling de méthode. Sans cela, les fonctionnalités clés de Firebase, telles que l'enregistrement FCM gestion, ne fonctionneront pas correctement.

Android

Services Google Play

FCM clients nécessitent des appareils équipés d'Android 7.0 ou version ultérieure sur lesquels les services Google Play sont installés, ou un émulateur exécutant Android 7.0 avec les API Google. Notez que vous n'êtes pas limité au déploiement de vos applications Android via le Google Play Store.

Les applications qui s'appuient sur le SDK Play Services doivent toujours vérifier si l'appareil dispose d'un APK des services Google Play compatible avant d'accéder aux fonctionnalités des services Google Play. Nous vous recommandons de le faire à deux endroits : dans la méthode onCreate() de l'activité principale et dans sa méthode onResume(). La vérification dans onCreate() garantit que l'application ne peut pas être utilisée sans une vérification réussie. La vérification dans onResume() garantit que si l'utilisateur revient à l'application en cours d'exécution par un autre moyen, par exemple via le bouton "Retour", la vérification est toujours effectuée.

Si l'appareil ne dispose pas d'une version compatible des services Google Play, votre application peut appeler GoogleApiAvailability.makeGooglePlayServicesAvailable() pour permettre aux utilisateurs de télécharger les services Google Play depuis le Play Store.

Web

Configurer les identifiants Web avec FCM

L'interface Web FCM utilise des identifiants Web appelés clés d'identification volontaire du serveur d'application (VAPID, Voluntary Application Server Identification) pour autoriser les requêtes d'envoi aux services de notification push Web compatibles. Pour abonner votre application aux notifications push, vous devez associer une paire de clés à votre projet Firebase. Vous pouvez soit générer une nouvelle paire de clés, soit importer votre paire de clés existante via la Firebase console.

Installer le plug-in FCM

1. Installez et initialisez les plug-ins Firebase pour Flutter si ce n'est pas déjà fait.

2. À la racine de votre projet Flutter, exécutez la commande suivante pour installer le plug-in :

   flutter pub add firebase_messaging
   

3. Une fois l'opération terminée, recréez votre application Flutter :

   flutter run
   

Demander une autorisation de notification

Pour envoyer un message de notification à un appareil, vous devez enregistrer l'appareil auprès de FCM à l'aide de register(). Si l'autorisation de notification n'a pas été accordée, cette méthode demande à l'utilisateur les autorisations de notification. Sinon, elle fournit le FID via onRegistered en cas de succès ou rejette l'avenir en raison d'une erreur.

// You may set the permission requests to "provisional" which allows the user to choose what type
// of notifications they would like to receive once the user receives a notification.
final notificationSettings = await FirebaseMessaging.instance.requestPermission(provisional: true);

// For apple platforms, make sure the APNS token is available before making any FCM plugin API calls
final apnsToken = await FirebaseMessaging.instance.getAPNSToken();
if (apnsToken != null) {
 // APNS token is available, make FCM plugin API requests...
}

Accéder à l'ID d'installation Firebase

Activer l'enregistrement à l'aide de l'ID d'installation Firebase

Pour activer l'enregistrement de votre instance d'application auprès de FCM à l'aide de l'ID d'installation Firebase (FID), vous devez d'abord activer les FID dans la configuration de votre application pour les plates-formes Android et Apple (aucune configuration d'activation statique n'est requise sur le Web) :

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

<key>FirebaseMessagingInstallationIdEnabled</key>
<true/>

S'abonner au flux onRegistered

Pour envoyer un message à l'instance de votre application sur un appareil spécifique, vous avez besoin de l' ID d'installation Firebase (FID) de cette instance d'application une fois qu'elle a été enregistrée auprès de FCM. Le FID est fourni de manière asynchrone via le flux onRegistered.

Sur les plates-formes Android et Apple, FCM enregistre automatiquement l'instance d'application au démarrage lorsque l'initialisation automatique est activée (par défaut). Toutefois, un appel explicite à register() est requis :

• Sur le Web. Vous pouvez éventuellement transmettre vapidKey et serviceWorkerScriptPath.
• Sur les plates-formes Android et Apple si l'initialisation automatique est désactivée ou après avoir appelé unregister(). Vous pouvez également appeler register() à tout moment pour déclencher onRegistered avec le FID déjà enregistré.

Abonnez-vous toujours à onRegistered avant d'appeler register() afin que votre écouteur soit actif lorsque l'événement d'enregistrement est émis :

final messaging = FirebaseMessaging.instance;

messaging.onRegistered
    .listen((String installationId) {
      // TODO: Send the Firebase Installation ID (FID) to your application server.
    })
    .onError((err) {
      // Error getting Firebase Installation ID.
    });

// Required on Web, and on Android/Apple if auto-initialization is disabled.
await messaging.register(
  // Optional on Web (ignored on Android and Apple platforms)
  vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu",
);

Le flux onRegistered émet le FID dans les scénarios suivants :

1. Automatiquement au démarrage initial de l'application et à la synchronisation de routine sur les plates-formes Android et Apple lorsque l'initialisation automatique est activée.
2. Chaque fois qu'un appel register() manuel se termine (même si l'instance d'application est déjà enregistrée, onRegistered émet toujours le FID déjà enregistré).
3. Chaque fois qu'un changement d'ID d'installation Firebase est détecté et que l'application est réenregistrée auprès de FCM, ou sur le Web lorsqu'un pushsubscriptionchange événement est déclenché.

Une fois que vous avez obtenu l'ID d'installation Firebase (FID), envoyez-le au serveur de votre application et stockez-le à l'aide de la méthode de votre choix.

Accéder au jeton d'enregistrement (obsolète)

Pour envoyer un message à un appareil spécifique, vous devez connaître le jeton d'enregistrement de l'appareil. Pour récupérer le jeton d'enregistrement d'une instance d'application, appelez getToken(). Si l'autorisation de notification n'a pas été accordée, cette méthode demande à l'utilisateur les autorisations de notification. Sinon, elle renvoie un jeton ou rejette l'avenir en raison d'une erreur.

Sur les plates-formes Web, transmettez votre clé publique VAPID à getToken() :

final fcmToken = await FirebaseMessaging.instance.getToken(vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu");

Pour être averti chaque fois que le jeton est mis à jour, abonnez-vous au flux onTokenRefresh :

FirebaseMessaging.instance.onTokenRefresh
    .listen((fcmToken) {
      // TODO: If necessary send token to application server.

      // Note: This callback is fired at each app startup and whenever a new
      // token is generated.
    })
    .onError((err) {
      // Error getting token.
    });

Empêcher l'initialisation automatique

Lorsqu'un enregistrement FCM est généré, la bibliothèque importe l'identifiant et les données de configuration dans Firebase. Si vous préférez empêcher l'enregistrement automatique, désactivez l'initialisation automatique au moment de la compilation.

Lorsque l'initialisation automatique est désactivée, vous pouvez enregistrer explicitement l'instance d'application au moment de l'exécution en appelant register() (assurez-vous de vous abonner d'abord à onRegistered pour recevoir l'ID d'installation Firebase) :

await FirebaseMessaging.instance.register();

iOS

Sur iOS, ajoutez une valeur de métadonnées à votre Info.plist :

FirebaseMessagingAutoInitEnabled = NO

Android

Sur Android, désactivez la collecte Analytics et l'initialisation automatique FCM (vous devez désactiver les deux) en ajoutant ces valeurs de métadonnées à votre AndroidManifest.xml :

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />

Réactiver FCM l'initialisation automatique au moment de l'exécution

Pour activer l'initialisation automatique pour une instance d'application spécifique, appelez setAutoInitEnabled() :

await FirebaseMessaging.instance.setAutoInitEnabled(true);

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

Envoyer un message de notification test

1. Installez et exécutez l'application sur l'appareil cible. Sur les appareils Apple, vous devrez accepter la demande d'autorisation de recevoir des notifications à distance.

2. Assurez-vous que l'application est en arrière-plan sur l'appareil.

3. Dans la console Firebase, accédez à DevOps et engagement > Messagerie.

4. Créez une campagne.

   • S'il s'agit de votre premier message :

     1. Sélectionnez Créer votre première campagne.

     2. Sélectionnez Messages de notification Firebase , puis Créer.

   • Si vous avez déjà créé des campagnes :

     1. Dans l'onglet Campagnes, sélectionnez Nouvelle campagne.

     2. Cliquez sur Notifications.

5. Saisissez le texte du message.

6. Sélectionnez Envoyer un message test dans le volet de droite.

7. Dans le champ Ajouter un ID d'installation Firebase ou FCM un jeton d'enregistrement, saisissez votre ID d'installation Firebase ou votre jeton d'enregistrement.

8. Sélectionnez Tester.

Une fois que vous avez sélectionné Tester, l'appareil client ciblé, avec l'application en arrière-plan, devrait recevoir la notification.

Pour obtenir des informations sur la diffusion des messages dans votre application, accédez au DevOps et engagement > Messagerie > Rapports dashboard dans la console Firebase. Ce tableau de bord enregistre le nombre de messages envoyés et ouverts sur les appareils Apple et Android, ainsi que les données sur les "impressions" (notifications vues par les utilisateurs) pour les applications Android.

Gérer les interactions

Lorsque les utilisateurs appuient sur une notification, le comportement par défaut sur Android et iOS consiste à ouvrir l'application. Si l'application est arrêtée, elle est démarrée. Si elle est en arrière-plan, elle est mise au premier plan.

Selon le contenu d'une notification, vous pouvez gérer l'interaction de l'utilisateur lorsque l'application s'ouvre. Par exemple, si un nouveau message de chat est envoyé à l'aide d'une notification et que l'utilisateur le sélectionne, vous pouvez ouvrir la conversation spécifique lorsque l'application s'ouvre.

Le package firebase-messaging offre deux façons de gérer cette interaction :

1. getInitialMessage(): Si l'application est ouverte à partir d'un état arrêté, cette méthode renvoie un Future contenant un RemoteMessage. Une fois consommé, le RemoteMessage est supprimé.
2. onMessageOpenedApp : unStream qui publie un RemoteMessage lorsque l' application est ouverte à partir d'un état en arrière-plan.

Pour garantir une expérience fluide à vos utilisateurs, vous devez gérer les deux scénarios. L'exemple de code suivant explique comment procéder :

class Application extends StatefulWidget {
  @override
  State createState() => _Application();
}

class _Application extends State {
  // In this example, suppose that all messages contain a data field with the key 'type'.
  Future setupInteractedMessage() async {
    // Get any messages which caused the application to open from
    // a terminated state.
    RemoteMessage? initialMessage =
        await FirebaseMessaging.instance.getInitialMessage();

    // If the message also contains a data property with a "type" of "chat",
    // navigate to a chat screen
    if (initialMessage != null) {
      _handleMessage(initialMessage);
    }

    // Also handle any interaction when the app is in the background using a
    // Stream listener
    FirebaseMessaging.onMessageOpenedApp.listen(_handleMessage);
  }

  void _handleMessage(RemoteMessage message) {
    if (message.data['type'] == 'chat') {
      Navigator.pushNamed(context, '/chat',
        arguments: ChatArguments(message),
      );
    }
  }

  @override
  void initState() {
    super.initState();

    // Run code required to handle interacted messages in an async function
    // as initState() must not be async
    setupInteractedMessage();
  }

  @override
  Widget build(BuildContext context) {
    return Text("...");
  }
}

La façon dont vous gérez l'interaction dépend de votre configuration. L'exemple présenté précédemment est un exemple de base d'utilisation d'un StatefulWidget.

Étapes suivantes

Une fois les étapes de configuration terminées, voici quelques options pour continuer à utiliser FCM pour Flutter :

• Envoyer des messages aux appareils
• Recevoir des messages dans une application Flutter
• Envoyer des messages à des sujets