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

Ce guide explique comment utiliser Firebase Cloud Messaging dans vos applications clientes pour les plates-formes Apple (comme iOS) afin d'envoyer des messages de manière fiable.

Pour les applications clientes Apple, vous pouvez recevoir des charges utiles de notification et de données d'une taille maximale de 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 la méthode swizzling 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 du traitement du rappel de message en aval. Les développeurs qui préfèrent ne pas utiliser le swizzling peuvent le désactiver en ajoutant l'indicateur 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 la méthode swizzling activée.

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 l'Apple Developer Member Center.

1. Dans la console Firebase, 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 l'un des trois.
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.

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 auprès de 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 à n'importe quelle instance 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 cibler les 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 auprès de 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 FID, 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 votre délégué d'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 à votre serveur d'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 de l'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 diffusion 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é : mappage de votre jeton APNs et de votre FID

Si vous avez désactivé la méthode swizzling ou si vous créez une application SwiftUI, vous devez explicitement mapper 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 (obsolète)

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. Comme le 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 votre délégué d'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 envoyés via la méthode messaging:didReceiveRegistrationToken:. Cette méthode est généralement appelée une fois par démarrage de l'application avec un 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 à votre serveur d'application.
• Abonnez le jeton d'enregistrement à des thèmes. Cela n'est nécessaire que pour les nouveaux abonnements ou lorsque 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 renvoyée si la récupération du jeton échoue.

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 déléguée. La propriété "token" contient toujours la valeur du jeton actuel.

Swizzling désactivé : mappage de votre jeton APNs et de votre jeton d'enregistrement

Si vous avez désactivé la méthode swizzling ou si vous créez une application SwiftUI, vous devez explicitement mapper 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 que lorsque le swizzling est 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 d'abord obtenir l'autorisation explicite des utilisateurs, 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 de l'extension FCM dans NotificationService.m. Plus précisément, au lieu d'effectuer le rappel avec self.contentHandler(self.bestAttemptContent);, effectuez-le avec FIRMessaging extensionHelper, comme indiqué ci-dessous :

@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 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 votre jeton d'enregistrement.

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.

Étapes suivantes

Une fois la configuration terminée, voici quelques options pour continuer à utiliser FCM pour les plates-formes Apple :

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