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

Ce guide explique comment faire vos premiers pas avec Firebase Cloud Messaging dans vos applications clientes pour la plate-forme Apple (comme iOS) afin de pouvoir envoyer des messages de manière fiable.

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

Pour écrire votre code client en Objective-C ou en Swift, nous vous recommandons d'utiliser l' API FIRMessaging. L' exemple de guide 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 FCM SDK effectue la méthode swizzling dans deux domaines clés : le mappage de votre jeton APNs au jeton d'enregistrement FCM et la capture des données d'analyse lors de la gestion des rappels de messages en aval. Les développeurs qui préfèrent ne pas utiliser la méthode swizzling peuvent la désactiver en ajoutant l'indicateur FirebaseAppDelegateProxyEnabled dans le fichier Info.plist de l'application et en le définissant sur NO (valeur booléenne). Les sections pertinentes des guides fournissent des exemples de code, both 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 n'en avez pas encore, veillez à en créer une dans l' Apple Developer Member Center.

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

2. Sous APNs authentication key (Clé d'authentification APNs) dans iOS app configuration (Configuration de l'application iOS), cliquez sur le bouton Upload (Importer) pour importer votre clé d'authentification de développement, votre clé d'authentification de production ou les deux. Au moins une est requise.

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

S'inscrire pour recevoir des 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 au jeton d'enregistrement

Par défaut, le FCM SDK 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 à 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 jeton d'enregistrement via FIRMessagingDelegate's messaging:didReceiveRegistrationToken: méthode. 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é FIRMessaging's delegate 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:.

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

Récupérer le 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 d'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 au serveur de votre application.
• Abonnez le jeton d'enregistrement à des sujets. Cela n'est nécessaire que pour les nouveaux abonnements ou dans les cas 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é.

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 it.

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é de jeton a toujours la valeur de jeton actuelle.

Méthode swizzling désactivée : mapper votre jeton APNs et votre jeton d'enregistrement

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

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 à l'aide des mêmes méthodes que lorsque la méthode swizzling est activée.

Empêcher l'initialisation automatique

Lorsqu'un jeton d'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 le consentement explicite des utilisateurs, vous pouvez empêcher la génération de jetons 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 est conservée lors des redémarrages de l'application.

Configurer l'extension de service de notification

Pour envoyer des notifications incluant des images sur les 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 des 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 les notifications dans APNs, puis ajoutez l'API d'assistance d'extension 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 s'exécute en arrière-plan sur l'appareil.
3. Dans la console Firebase, ouvrez la page Messaging.
4. S'il s'agit de votre premier message, sélectionnez Create your first campaign (Créer votre première campagne).
   1. Sélectionnez Firebase Notification messages (Messages de notification Firebase), puis Create (Créer).
5. Sinon, dans l'onglet Campaigns (Campagnes), sélectionnez New campaign (Nouvelle campagne), puis Notifications.
6. Saisissez le texte du message.
7. Sélectionnez Send test message (Envoyer un message test) dans le volet de droite.
8. Dans le champ Add an FCM registration token (Ajouter un jeton d'enregistrement), saisissez votre jeton d'enregistrement.
9. Sélectionnez Test (Tester).

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

Pour en savoir plus sur la diffusion des messages dans votre application, consultez le FCM tableau de bord, de reporting qui enregistre le nombre de messages envoyés et ouverts sur les appareils Apple et Android.

Étapes suivantes

Une fois les étapes de configuration terminées, voici quelques options pour continuer à utiliser avec FCM pour les plates-formes Apple :

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