Premiers pas avec Firebase Cloud Messaging dans les applications de la plate-forme Apple

Ce guide explique comment commencer à utiliser Firebase Cloud Messaging dans vos applications clientes de plate-forme Apple (comme iOS) pour pouvoir envoyer des messages de manière fiable.

Pour les applications clientes Apple, vous pouvez recevoir des notifications et des charges utiles de données jusqu'à 4 096 octets via l'interface APNs Firebase Cloud Messaging.

Pour écrire votre code client en Objective-C ou Swift, nous vous recommandons d'utiliser l'API FIRMessaging. L'exemple de démarrage rapide fournit un exemple de code pour les deux langages.

Avant de commencer, ajoutez Firebase à votre projet Apple.

Méthode swizzling dans Firebase Cloud Messaging

Le SDK FCM effectue le swizzling de méthode dans deux domaines clés : le mappage de votre jeton APNs à l'ID d'installation Firebase ou au jeton d'enregistrement FCM, et la capture des données analytiques lors de la gestion des rappels de messages en aval. Les développeurs qui préfèrent ne pas utiliser le swizzling peuvent le désactiver en ajoutant le flag FirebaseAppDelegateProxyEnabled dans le fichier Info.plist de l'application et en le définissant sur la valeur booléenne NO. Les sections pertinentes des guides fournissent des exemples de code, avec et sans swizzling de méthode activé.

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 la consoleFirebase, accédez à settings Paramètres > Général. Cliquez ensuite sur l'onglet Cloud Messaging.
2. Dans Clé d'authentification APNs sous Configuration de l'application iOS, cliquez sur 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 le Centre des membres Apple Developer), puis cliquez sur Importer.

S'inscrire aux notifications à distance

UNUserNotificationCenter.current().delegate = self

let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
UNUserNotificationCenter.current().requestAuthorization(
  options: authOptions,
  completionHandler: { _, _ in }
)

application.registerForRemoteNotifications()
MigratedSnippets.swift

[UNUserNotificationCenter currentNotificationCenter].delegate = self;
UNAuthorizationOptions authOptions = UNAuthorizationOptionAlert |
    UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
[[UNUserNotificationCenter currentNotificationCenter]
    requestAuthorizationWithOptions:authOptions
    completionHandler:^(BOOL granted, NSError * _Nullable error) {
      // ...
    }];

[application registerForRemoteNotifications];
ObjCMigratedSnippets.m

Accéder à l'ID d'installation Firebase

Par défaut, le SDK FCM enregistre l'instance d'application avec FCM et renvoie un ID d'installation Firebase (FID) pour l'instance d'application cliente au lancement de l'application. Comme le jeton d'appareil APNs, ce FID vous permet d'envoyer des notifications ciblées à une instance particulière de votre application.

De la même manière que les plates-formes Apple fournissent généralement un jeton d'appareil APNs au démarrage de l'application, FCM fournit un FID pour le ciblage des notifications. Le SDK FCM fournit le FID à l'aide de la méthode messaging:didReceiveRegistration: de FIRMessagingDelegate, surveille automatiquement les modifications du FID et appelle la méthode avec un nouveau FID lorsqu'une modification est détectée. Nous vous recommandons de récupérer et d'importer régulièrement le FID, car il peut changer après le démarrage initial.

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

Pour activer l'enregistrement de votre instance d'application avec FCM à l'aide de l' ID d'installation Firebase (FID), ajoutez l'indicateur de métadonnées suivant à votre fichier Info.plist, et non à votre fichier GoogleService-Info.plist :

FirebaseMessagingInstallationIdEnabled = YES

Définir le délégué de messagerie

Pour recevoir des FIDs, implémentez le protocole de délégué de messagerie et définissez la propriété delegate de FIRMessaging après avoir appelé [FIRApp configure]. Par exemple, si le délégué de votre application est conforme au protocole de délégué de messagerie, vous pouvez définir le délégué sur application:didFinishLaunchingWithOptions: sur lui-même.

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

Implémenter la méthode didReceiveRegistration

Les instances d'application sont ciblées à l'aide du FID une fois l'enregistrement terminé. Pour recevoir le FID lors de l'enregistrement, implémentez la méthode messaging:didReceiveRegistration:. Cette méthode est généralement appelée une fois par démarrage de l'application avec le FID. Lorsque cette méthode est appelée, vous pouvez effectuer les actions suivantes :

• Si vous n'avez pas envoyé le FID à votre serveur ou si vous l'avez envoyé récemment, envoyez-le au serveur de votre application.
• Si l'abonnement est nouveau ou si l'utilisateur a réinstallé l'application, abonnez le FID aux thèmes.

func messaging(_ messaging: Messaging, didReceiveRegistration installationId: String?) {
  print("Firebase Installation ID: \(String(describing: installationId))")
  // Note: This callback is fired at each app startup.

  if let installationId = installationId {
    // Send the Firebase Installation ID to your app server.
    sendRegistrationToServer(installationId)
  }
}
    

- (void)messaging:(FIRMessaging *)messaging didReceiveRegistration:(nullable NSString *)installationId {
  NSLog(@"Firebase Installation ID: %@", installationId);
  // Note: This callback is fired at each app startup.

  if (installationId != nil) {
    // Send the Firebase Installation ID to your app server.
    [self sendRegistrationToServer:installationId];
  }
}
    

Enregistrer manuellement lorsque l'initialisation automatique est désactivée

Si vous avez désactivé l'initialisation automatique, le SDK FCM n'enregistrera pas automatiquement l'instance d'application auprès de FCM au démarrage de l'application. Vous devez appeler register au démarrage de l'application pour déclencher l'enregistrement et la remise du FID via la méthode messaging:didReceiveRegistration: :

// Trigger manual registration if auto-initialization is turned off.
Messaging.messaging().register { error in
    if let error = error {
        // Handle the error
        print("Failed registering: \(error)")
        return
    }
    // Registration was successful. FID is delivered through the messaging:didReceiveRegistration: method.
    print("Successfully registered.")
}
    

// Trigger manual registration if auto-initialization is turned off.
[[FIRMessaging messaging] registerWithCompletion:^(NSError * _Nullable error) {
    if (error) {
        // Handle the error
        NSLog(@"Failed registering: %@", error);
        return;
    }
    // Registration was successful. FID is delivered through the messaging:didReceiveRegistration: method.
    NSLog(@"Successfully registered.");
}];
    

Swizzling désactivé : mapper votre jeton APNs et votre FID

Si vous avez désactivé le swizzling de méthode ou si vous créez une application SwiftUI, vous devez mapper explicitement votre jeton APNs aux ID d'installation Firebase (FID). Implémentez la méthode application(_:didRegisterForRemoteNotificationsWithDeviceToken:) pour récupérer le jeton APNs, puis définissez la propriété apnsToken de Messaging :

func application(application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  Messaging.messaging().apnsToken = deviceToken
}

// With "FirebaseAppDelegateProxyEnabled": NO
- (void)application:(UIApplication *)application
    didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [FIRMessaging messaging].APNSToken = deviceToken;
}

Une fois le FID enregistré, vous pouvez y accéder et écouter les événements d'actualisation en utilisant les mêmes méthodes que lorsque le swizzling est activé.

Accéder au jeton d'enregistrement

Par défaut, le SDK FCM génère un jeton d'enregistrement pour l'instance de l'application cliente au lancement de l'application. Semblable au jeton d'appareil APNs, ce jeton vous permet d'envoyer des notifications ciblées à une instance particulière de votre application.

De la même manière que les plates-formes Apple fournissent généralement un jeton d'appareil APNs au démarrage de l'application, FCM fournit un jeton d'enregistrement via la méthode messaging:didReceiveRegistrationToken: de FIRMessagingDelegate. Le SDK FCM récupère un jeton nouveau ou existant lors du lancement initial de l'application et chaque fois que le jeton est mis à jour ou invalidé. Dans tous les cas, le SDK FCM appelle messaging:didReceiveRegistrationToken: avec un jeton valide.

Le jeton d'enregistrement peut changer dans les cas suivants :

• L'application est restaurée sur un nouvel appareil
• L'utilisateur désinstalle/réinstalle l'application
• L'utilisateur efface les données de l'application.

Définir le délégué de messagerie

Pour recevoir des jetons d'enregistrement, implémentez le protocole de délégué de messagerie et définissez la propriété delegate de FIRMessaging après avoir appelé [FIRApp configure]. Par exemple, si le délégué de votre application est conforme au protocole de délégué de messagerie, vous pouvez définir le délégué sur application:didFinishLaunchingWithOptions: sur lui-même.

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

Récupération du jeton d'enregistrement actuel

Les jetons d'enregistrement sont fournis via la méthode messaging:didReceiveRegistrationToken:. Cette méthode est généralement appelée une fois par démarrage de l'application avec le jeton d'enregistrement. Lorsque cette méthode est appelée, c'est le moment idéal pour :

• Si le jeton d'enregistrement est nouveau, envoyez-le au serveur de votre application.
• Abonnez le jeton d'enregistrement à des thèmes. Cela n'est requis que pour les nouveaux abonnements ou dans les situations où l'utilisateur a réinstallé l'application.

Vous pouvez récupérer le jeton directement à l'aide de token(completion:). Une erreur non nulle est fournie si la récupération du jeton a échoué d'une manière ou d'une autre.

Messaging.messaging().token { token, error in
  if let error = error {
    print("Error fetching remote FCM registration token: \(error)")
  } else if let token = token {
    print("Remote instance ID token: \(token)")
  }
}

[[FIRMessaging messaging] tokenWithCompletion:^(NSString * _Nullable token, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"Error fetching the remote FCM registration token: %@", error);
  } else {
    NSLog(@"Remote FCM registration token: %@", token);
    NSString* message =
      [NSString stringWithFormat:@"FCM registration token: %@", token];
    // display message
    NSLog(@"%@", message);
  }
}];

Vous pouvez utiliser cette méthode à tout moment pour accéder au jeton au lieu de le stocker.

Surveiller l'actualisation des jetons

Pour être averti chaque fois que le jeton est mis à jour, fournissez un délégué conforme au protocole de délégué de messagerie. L'exemple suivant enregistre le délégué et ajoute la méthode de délégué appropriée :

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
  print("Firebase registration token: \(String(describing: 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.
}
MigratedSnippets.swift

- (void)messaging:(FIRMessaging *)messaging didReceiveRegistrationToken:(NSString *)fcmToken {
    NSLog(@"FCM registration token: %@", fcmToken);
    // Notify about received token.
    NSDictionary *dataDict = [NSDictionary dictionaryWithObject:fcmToken forKey:@"token"];
    [[NSNotificationCenter defaultCenter] postNotificationName:
     @"FCMToken" object:nil userInfo:dataDict];
    // TODO: If necessary send token to application server.
    // Note: This callback is fired at each app startup and whenever a new token is generated.
}
ObjCMigratedSnippets.m

Vous pouvez également écouter un NSNotification nommé kFIRMessagingRegistrationTokenRefreshNotification au lieu de fournir une méthode de délégué. La propriété du jeton a toujours la valeur du jeton actuel.

Swizzling désactivé : mapper votre jeton APNs et votre jeton d'enregistrement

Si vous avez désactivé le swizzling de méthode ou si vous créez une application SwiftUI, vous devrez mapper explicitement votre jeton APNs au jeton d'enregistrement FCM. Implémentez la méthode application(_:didRegisterForRemoteNotificationsWithDeviceToken:) pour récupérer le jeton APNs, puis définissez la propriété apnsToken de Messaging :

func application(application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  Messaging.messaging().apnsToken = deviceToken
}

// With "FirebaseAppDelegateProxyEnabled": NO
- (void)application:(UIApplication *)application
    didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [FIRMessaging messaging].APNSToken = deviceToken;
}

Une fois le jeton d'enregistrement FCM généré, vous pouvez y accéder et écouter les événements d'actualisation en utilisant les mêmes méthodes qu'avec le swizzling activé.

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 souhaitez obtenir un consentement explicite des utilisateurs au préalable, vous pouvez empêcher l'enregistrement automatique au moment de la configuration en désactivant FCM. Pour ce faire, ajoutez une valeur de métadonnées à votre Info.plist (et non à votre GoogleService-Info.plist) :

FirebaseMessagingAutoInitEnabled = NO

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

Messaging.messaging().autoInitEnabled = true

[FIRMessaging messaging].autoInitEnabled = YES;

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

Configurer l'extension du service de notification

Pour envoyer des notifications incluant des images aux appareils Apple, vous devez ajouter une extension de service de notification. Cette extension permet aux appareils d'afficher les images fournies dans la charge utile de la notification. Si vous ne prévoyez pas d'envoyer d'images dans les notifications, vous pouvez ignorer cette étape.

Pour ajouter une extension de service, effectuez les tâches de configuration requises pour modifier et présenter des notifications dans APNs, puis ajoutez l'API d'assistance pour les extensions FCM dans NotificationService.m. Plus précisément, au lieu de terminer le rappel avec self.contentHandler(self.bestAttemptContent);, terminez-le avec FIRMessaging extensionHelper comme indiqué :

@interface NotificationService () <NSURLSessionDelegate>
@property(nonatomic) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property(nonatomic) UNMutableNotificationContent *bestAttemptContent;
@end

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.contentHandler = contentHandler;
self.bestAttemptContent = [request.content mutableCopy];

    // Modify the notification content here as you want
self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]",
self.bestAttemptContent.title];

  // Call FIRMessaging extension helper API.
  [[FIRMessaging extensionHelper] populateNotificationContent:self.bestAttemptContent
withContentHandler:contentHandler];

}
...

Envoyer un message de notification

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

2. Vérifiez 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.

   • Si c'est 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. Dans le volet de droite, sélectionnez Envoyer un message test.

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

8. Sélectionnez Tester.

Après avoir sélectionné Tester, l'appareil client ciblé, avec l'application en arrière-plan, devrait recevoir la notification.

Pour obtenir des informations sur la distribution des messages à 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.

Étapes suivantes

Une fois les étapes de configuration terminées, voici quelques options pour aller plus loin avec FCM pour les plates-formes Apple :

• Envoyer des messages aux appareils
• Recevoir des messages dans une application Apple
• Envoyer des messages à des thèmes