Premiers pas avec Firebase Cloud Messaging dans les applications Flutter

Sélectionnez une plate-forme : iOS+ Android Web Flutter Unity C++


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

Selon la plate-forme que vous ciblez, vous devrez effectuer des étapes de configuration supplémentaires.

iOS+

Méthode swizzling

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

Android

Services Google Play

Les clients FCM nécessitent des appareils équipés d'Android 7.0 ou version ultérieure sur lesquels les services Google Play sont également 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 des services Play doivent toujours vérifier que 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() permet de s'assurer 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 VAPID (Voluntary Application Server Identification) pour autoriser l'envoi de requêtes aux services Web Push compatibles. Pour abonner votre application aux notifications push, vous devez associer une paire de clés à votre projet Firebase. Vous pouvez générer une nouvelle paire de clés ou importer votre paire de clés existante via la console Firebase.

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, recompilez votre application Flutter :

    flutter run

Demander une autorisation de notification

Pour envoyer un message de notification à un appareil, vous devez l'enregistrer auprès de FCM à l'aide de register(). Si l'autorisation de notification n'a pas été accordée, cette méthode la demande à l'utilisateur. Sinon, il fournit le FID via onRegistered en cas de réussite ou rejette le futur 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 permettre 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) :

Android

Ajoutez l'élément <meta-data> suivant dans l'élément <application> de votre AndroidManifest.xml :

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

iOS+

Ajoutez la clé FirebaseMessagingInstallationIdEnabled à votre Info.plist et définissez-la sur true (YES) :

<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 diffusé 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 l'appel de 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 lors de 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 événement pushsubscriptionchange est déclenché.

Une fois que vous avez obtenu l'ID d'installation Firebase (FID), envoyez-le à votre serveur d'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 de l'accorder. Sinon, il renvoie un jeton ou rejette le futur 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() (veillez à 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 de 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 l'initialisation automatique de FCM 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 de test

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

  2. Assurez-vous que l'application s'exécute 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 un jeton d'enregistrement FCM, saisissez l'ID d'installation Firebase ou le jeton d'enregistrement que vous avez enregistrés.

  8. Sélectionnez Tester.

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

Pour en savoir plus sur la distribution des messages dans votre application, accédez au tableau de bord DevOps et engagement > Messagerie > Rapports 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 sera démarrée. Si elle est en arrière-plan, elle sera 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 propose 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 sera supprimé.
  2. onMessageOpenedApp : Stream qui publie un RemoteMessage lorsque l'application est ouverte depuis un état d'arrière-plan.

Pour que vos utilisateurs bénéficient d'une expérience fluide, vous devez gérer les deux scénarios. L'exemple de code suivant montre 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 la configuration terminée, voici quelques options pour continuer à utiliser FCM pour Flutter :