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

Sélectionnez une plate-forme :

iOS+ Android Web Flutter Unity C++

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 SDK FCM effectue la méthode swizzling dans deux domaines clés : le mappage de votre jeton APNs à l'ID d'installation Firebase ou le jeton FCM d'enregistrement, et la capture des données Analytics 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 au 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.

Important : Avec le SDK Firebase Unity sur iOS, ne désactivez pas la méthode swizzling. Elle est requise par le SDK. Sans elle, les fonctionnalités clés de Firebase telles que la gestion de l'enregistrement FCM ne fonctionnent pas correctement.

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 la console Firebase, accédez à Settings > General. Cliquez ensuite sur l'onglet Cloud Messaging.
2. Sous APNs authentication key (Clé d'authentification APNs) dans iOS app configuration (Configuration de l'application iOS), cliquez sur 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 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

Au démarrage ou au point souhaité de votre flux d'application, enregistrez votre application pour recevoir des notifications à distance. Appelez registerForRemoteNotifications comme indiqué :

Remarque : Les applications SwiftUI doivent utiliser les wrappers de propriété UIApplicationDelegateAdaptor ou NSApplicationDelegateAdaptor pour fournir un type correspondant au protocole de délégué d'application approprié.

Swift

UNUserNotificationCenter.current().delegate = self

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

application.registerForRemoteNotifications()
MigratedSnippets.swift

Objective-C

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

[application registerForRemoteNotifications];
ObjCMigratedSnippets.m

Vous devez attribuer la propriété delegate de UNUserNotificationCenter et la propriété delegate de FIRMessaging. Par exemple, dans une application iOS, attribuez-la dans la applicationWillFinishLaunchingWithOptions: ou applicationDidFinishLaunchingWithOptions: méthode du délégué d'application.

Accéder à l'ID d'installation Firebase

Conseil : Consultez Bonnes pratiques pour la gestion de l'enregistrement FCM pour obtenir des conseils sur la gestion des enregistrements.

Les applications qui utilisent encore des API d'ID d'instance obsolètes pour la gestion des enregistrements doivent mettre à jour toute la logique d'enregistrement afin d'utiliser les API FCM décrites ici.

Par défaut, le FCM SDK 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 FCM SDK fournit le FID à l'aide de la méthode FIRMessagingDelegate's messaging:didReceiveRegistration:, 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.

Pour en savoir plus sur le moment où les FID sont réémis et sur la façon de les surveiller manuellement, consultez Surveiller le cycle de vie de 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), 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 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:.

Swift

Messaging.messaging().delegate = self

Objective-C

[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 messaging:didReceiveRegistration: méthode. Cette méthode est généralement appelée une fois par démarrage d'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 à des sujets.

Swift

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)
  }
}
    

Objective-C

- (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];
  }
}
    

S'inscrire manuellement lorsque l'initialisation automatique est désactivée

Si vous avez désactivé l'initialisation automatique, le FCM SDK n'enregistre 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 diffusion du FID via la méthode messaging:didReceiveRegistration: :

Swift

// 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.")
}
    

Objective-C

// 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.");
}];
    

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

Si vous avez désactivé la méthode swizzling 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 :

Swift

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

Objective-C

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

Accéder au jeton d'enregistrement

Conseil : Consultez Bonnes pratiques pour la gestion de l'enregistrement FCM pour obtenir des conseils sur la gestion des enregistrements.

Par défaut, le FCM SDK génère un jeton d'enregistrement pour l'instance d'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.

Les applications qui utilisent encore des API d'ID d'instance obsolètes pour la gestion des enregistrements doivent mettre à jour toute la logique d'enregistrement afin d'utiliser les API FCM décrites ici.

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

Swift

Messaging.messaging().delegate = self

Objective-C

[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 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 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é d'une manière ou d'une autre.

Swift

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)")
  }
}

Objective-C

[[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 du jeton

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 :

Swift

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

Objective-C

- (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 actuelle du jeton.

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 :

Swift

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

Objective-C

// 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 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 un consentement explicite des utilisateurs, vous pouvez empêcher l'enregistrement automatique lors 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 :

Swift

Messaging.messaging().autoInitEnabled = true

Objective-C

[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 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, accédez à DevOps & Engagement > Messaging

4. Créez une campagne.

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

     1. Sélectionnez Create your first campaign (Créer votre première campagne).

     2. Sélectionnez Firebase Notification messages (Messages de notification Firebase), puis Create (Créer).

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

     1. Dans l'onglet Campaigns (Campagnes), sélectionnez New campaign (Nouvelle campagne).

     2. Cliquez sur Notifications.

5. Saisissez le texte du message et envoyez-le.

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

7. Dans le champ Add a Firebase Installation ID or FCM registration token (Ajouter un ID d'installation Firebase ou un jeton d'enregistrement), saisissez votre jeton d'enregistrement.

8. Sélectionnez Test.

Après avoir sélectionné Test, 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 & Engagement > Messaging > Reports dashboard dans la Firebase console. 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 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