تلقّي الرسائل باستخدام "المراسلة عبر السحابة الإلكترونية من Firebase"

يوضّح هذا الدليل كيفية إعداد Firebase Cloud Messaging في تطبيقات العميل على الأجهزة الجوّالة والويب لتتمكّن من تلقّي الرسائل بشكل موثوق.

بعد تثبيت تطبيق العميل على أحد الأجهزة، يمكنه تلقّي الرسائل من خلال واجهة FCM APNs. يمكنك البدء على الفور في إرسال الإشعارات إلى شرائح المستخدمين باستخدام أداة إنشاء الإشعارات أو الرسائل التي تم إنشاؤها على خادم التطبيق.

التعامل مع إشعارات التنبيه

تُرسِل FCM جميع الرسائل التي تستهدف تطبيقات Apple من خلال APNs. لمزيد من المعلومات حول تلقّي إشعارات APNs باستخدام UNUserNotificationCenter، راجِع مستندات Apple حول التعامل مع الإشعارات والإجراءات ذات الصلة بالإشعارات.

يجب ضبط مفوّض UNUserNotificationCenter وتنفيذ طرق التفويض المناسبة لتلقّي إشعارات العرض من FCM.

Swift

// Receive displayed notifications for iOS 10+ devices.
func userNotificationCenter(_ center: UNUserNotificationCenter,
                            willPresent notification: UNNotification) async
  -> UNNotificationPresentationOptions {
  let userInfo = notification.request.content.userInfo

  // With swizzling disabled you must let Messaging know about the message, for Analytics
  // Messaging.messaging().appDidReceiveMessage(userInfo)

  // ...

  // Print full message.
  print(userInfo)

  // Change this to your preferred presentation option
  // Note: UNNotificationPresentationOptions.alert has been deprecated.
  return [.list, .banner, .sound]
}

func userNotificationCenter(_ center: UNUserNotificationCenter,
                            didReceive response: UNNotificationResponse) async {
  let userInfo = response.notification.request.content.userInfo

  // ...

  // Print full message.
  print(userInfo)
}

Objective-C

// Receive displayed notifications for iOS 10+ devices.
// Handle incoming notification messages while app is in the foreground.
- (void)userNotificationCenter:(UNUserNotificationCenter *)center
       willPresentNotification:(UNNotification *)notification
         withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
  NSDictionary *userInfo = notification.request.content.userInfo;

  // With swizzling disabled you must let Messaging know about the message, for Analytics
  // [[FIRMessaging messaging] appDidReceiveMessage:userInfo];

  // Print full message.
  NSLog(@"%@", userInfo);

  // Change this to your preferred presentation option
  completionHandler(UNNotificationPresentationOptionList |
                    UNNotificationPresentationOptionBanner |
                    UNNotificationPresentationOptionSound);
}

- (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.
}

- (void)logFCMToken {
  NSString *fcmToken = [FIRMessaging messaging].FCMToken;
  NSLog(@"Local FCM registration token: %@", fcmToken);

  NSString* displayToken = [NSString stringWithFormat:@"Logged FCM token: %@", fcmToken];

  [[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);
    }
  }];
  NSLog(@"%@", displayToken);
}

- (void)subsribeToTopic {
  [[FIRMessaging messaging] subscribeToTopic:@"weather"
                                  completion:^(NSError * _Nullable error) {
    NSLog(@"Subscribed to weather topic");
  }];
}

@end

إذا أردت إضافة إجراءات مخصّصة إلى إشعاراتك، اضبط المَعلمة click_action في حمولة الإشعارات. استخدِم القيمة التي تستخدمها للمفتاح category في حمولة APNs. يجب تسجيل الإجراءات المخصّصة قبل استخدامها. لمزيد من المعلومات، راجِع دليل برمجة الإشعارات المحلية والبعيدة من Apple.

للحصول على إحصاءات حول وصول الرسائل إلى تطبيقك، اطّلِع على FCM لوحة بيانات التقارير التي تسجّل عدد الرسائل المرسَلة والمفتوحة على أجهزة Apple وAndroid، بالإضافة إلى بيانات "مرات الظهور" (الإشعارات التي يراها المستخدمون) لتطبيقات Android.

التعامل مع الإشعارات الفورية الصامتة

عند إرسال الرسائل باستخدام مفتاح content-available (المكافئ لمفتاح APNs‏ content-available)، سيتم تسليم الرسائل كإشعارات صامتة، ما يؤدي إلى تنشيط تطبيقك في الخلفية لتنفيذ مهام مثل إعادة تحميل البيانات في الخلفية. وعلى عكس الإشعارات التي تظهر في المقدّمة، يجب التعامل مع هذه الإشعارات باستخدام الطريقة application(_:didReceiveRemoteNotification:fetchCompletionHandler:).

نفِّذ application(_:didReceiveRemoteNotification:fetchCompletionHandler:) كما هو موضّح:

Swift

@MainActor
func application(_ application: UIApplication,
                 didReceiveRemoteNotification userInfo: [AnyHashable: Any]) async
  -> UIBackgroundFetchResult {
  // If you are receiving a notification message while your app is in the background,
  // this callback will not be fired till the user taps on the notification launching the application.
  // TODO: Handle data of notification

  // With swizzling disabled you must let Messaging know about the message, for Analytics
  // Messaging.messaging().appDidReceiveMessage(userInfo)

  // ...

  // Print full message.
  print(userInfo)
  print("Call exportDeliveryMetricsToBigQuery() from AppDelegate")
  Messaging.serviceExtension().exportDeliveryMetricsToBigQuery(withMessageInfo: userInfo)
  return UIBackgroundFetchResult.newData
}

Objective-C

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
    fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
  // If you are receiving a notification message while your app is in the background,
  // this callback will not be fired until the user taps on the notification launching the application.
  // TODO: Handle data of notification

  // With swizzling disabled you must let Messaging know about the message, for Analytics
  // [[FIRMessaging messaging] appDidReceiveMessage:userInfo];

  // Print full message.
  NSLog(@"%@", userInfo);

  completionHandler(UIBackgroundFetchResultNewData);
}

لا تضمن منصات Apple تسليم الإشعارات التي تظهر في الخلفية. للتعرّف على الشروط التي يمكن أن تؤدي إلى تعذُّر ظهور الإشعارات في الخلفية، راجِع مستندات Apple حول إرسال التحديثات في الخلفية إلى تطبيقك.

تفسير حمولة رسالة الإشعار

حمولة رسائل الإشعارات هي قاموس من المفاتيح والقيم. تتضمّن رسائل الإشعارات المُرسَلة من خلال APNs تنسيق حمولة APNs التالي:

  {
    "aps" : {
      "alert" : {
        "body" : "great match!",
        "title" : "Portugal vs. Denmark",
      },
      "badge" : 1,
    },
    "customKey" : "customValue"
  }

التعامل مع الرسائل مع إيقاف ميزة "استبدال الرمز البرمجي للدالة"

بشكلٍ تلقائي، إذا خصّصت فئة مفوّض تطبيقك لسمتَي التفويض UNUserNotificationCenter وMessaging، ستعمل FCM على تبديل فئة مفوّض تطبيقك لربط الرمز المميّز FCM تلقائيًا بالرمز المميّز لخدمة APNs الخاص بالجهاز وتمرير أحداث تلقّي الإشعارات إلى Analytics. إذا أوقفت ميزة "تبديل الطرق" بشكل صريح، أو إذا كنت بصدد إنشاء تطبيق SwiftUI، أو إذا كنت تستخدم فئة منفصلة لأي من المندوبين، عليك تنفيذ هاتين المهمتين يدويًا.

لربط الرمز المميّز FCM بالرمز المميّز لخدمة APNs الخاص بالجهاز، مرِّر الرمز المميّز لخدمة APNs إلى الفئة Messaging في معالج إعادة تحميل الرمز المميّز في مفوّض تطبيقك باستخدام السمة apnsToken.

Swift

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

Objective-C

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

لنقل معلومات استلام الإشعارات إلى Analytics، استخدِم طريقة appDidReceiveMessage(_:).

Swift

func userNotificationCenter(_ center: UNUserNotificationCenter,
                            willPresent notification: UNNotification,
  withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
  let userInfo = notification.request.content.userInfo

  Messaging.messaging().appDidReceiveMessage(userInfo)

  // Change this to your preferred presentation option
  completionHandler([[.alert, .sound]])
}

func userNotificationCenter(_ center: UNUserNotificationCenter,
                            didReceive response: UNNotificationResponse,
                            withCompletionHandler completionHandler: @escaping () -> Void) {
  let userInfo = response.notification.request.content.userInfo

  Messaging.messaging().appDidReceiveMessage(userInfo)

  completionHandler()
}

func application(_ application: UIApplication,
didReceiveRemoteNotification userInfo: [AnyHashable : Any],
  fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
  Messaging.messaging().appDidReceiveMessage(userInfo)
  completionHandler(.noData)
}

Objective-C

- (void)userNotificationCenter:(UNUserNotificationCenter *)center
      willPresentNotification:(UNNotification *)notification
        withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
  NSDictionary *userInfo = notification.request.content.userInfo;

  [[FIRMessaging messaging] appDidReceiveMessage:userInfo];

  // Change this to your preferred presentation option
  completionHandler(UNNotificationPresentationOptionBadge | UNNotificationPresentationOptionAlert);
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center
didReceiveNotificationResponse:(UNNotificationResponse *)response
        withCompletionHandler:(void(^)(void))completionHandler {
  NSDictionary *userInfo = response.notification.request.content.userInfo;

  [[FIRMessaging messaging] appDidReceiveMessage:userInfo];

  completionHandler();
}

- (void)application:(UIApplication *)application
didReceiveRemoteNotification:(NSDictionary *)userInfo
fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler {
  [[FIRMessaging messaging] appDidReceiveMessage:userInfo];
  completionHandler(UIBackgroundFetchResultNoData);
}