بدء استخدام "المراسلة عبر السحابة الإلكترونية من Firebase" في تطبيقات منصة Apple

يوضّح هذا الدليل كيفية البدء باستخدام Firebase Cloud Messaging في تطبيقات العميل على منصة Apple (مثل iOS) حتى تتمكّن من إرسال الرسائل بشكل موثوق.

بالنسبة إلى تطبيقات العميل على Apple، يمكنك تلقّي إشعارات وحِملات بيانات يصل حجمها إلى 4096 بايت من خلال واجهة برمجة تطبيقات إشعارات Apple الفورية (APNs) Firebase Cloud Messaging.

لكتابة رمز العميل بلغة Objective-C أو Swift، ننصحك باستخدام الـ FIRMessaging API. يقدّم مثال البدء السريع رمزًا نموذجيًا لكلتا اللغتَين.

قبل البدء، أضِف Firebase إلى مشروع Apple.

تغيير وظيفة الإجراء في Firebase Cloud Messaging

تُجري حزمة تطوير البرامج (SDK) لـ FCM تغيير وظيفة الإجراء في مجالَين رئيسيَين: ربط رمز إشعارات Apple الفورية (APNs) برمز التسجيل في FCM وجمع بيانات الإحصاءات أثناء معالجة معاودة الاتصال بالرسائل الواردة. يمكن للمطوّرين الذين يفضّلون عدم استخدام تغيير وظيفة الإجراء إيقافه من خلال إضافة العلامة FirebaseAppDelegateProxyEnabled في ملف Info.plist الخاص بالتطبيق وضبطها على NO (قيمة منطقية). توفّر الأقسام ذات الصلة في الأدلة أمثلة على الرموز البرمجية، سواء مع تفعيل تغيير وظيفة الإجراء أو بدونه.

تحميل مفتاح مصادقة إشعارات Apple الفورية (APNs)

حمِّل مفتاح مصادقة إشعارات Apple الفورية (APNs) إلى Firebase. إذا لم يكن لديك مفتاح مصادقة إشعارات Apple الفورية (APNs)، احرص على إنشاء مفتاح في Apple Developer Member Center.

1. داخل مشروعك في وحدة تحكّم Firebase، انقر على رمز الترس، ثم على إعدادات المشروع، وبعد ذلك على علامة التبويب خدمة المراسلة عبر السحابة الإلكترونية.

2. في مفتاح مصادقة إشعارات Apple الفورية (APNs) ضِمن إعداد تطبيق iOS، انقر على الزر تحميل لتحميل مفتاح مصادقة التطوير أو مفتاح مصادقة الإنتاج أو كليهما. ويجب توفير مفتاح واحد على الأقل.

3. انتقِل إلى الموقع الذي حفظت فيه المفتاح، واختَره، ثم انقر على فتح. أضِف رقم تعريف المفتاح (المتاح في Apple Developer Member Center) وانقر على تحميل.

التسجيل لتلقّي الإشعارات عن بُعد

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

الوصول إلى رمز التسجيل

تُنشئ حزمة تطوير البرامج (SDK) لـ FCM تلقائيًا رمز تسجيل لمثيل تطبيق العميل عند تشغيل التطبيق. على غرار رمز جهاز إشعارات Apple الفورية (APNs)، يتيح لك هذا الرمز إرسال إشعارات مستهدَفة إلى أيّ مثيل معيّن من تطبيقك.

على غرار الطريقة التي تُرسِل بها منصات Apple عادةً رمزًا مميزًا لجهاز إشعارات Apple الفورية (APNs) عند بدء تشغيل التطبيق، توفّر "مراسلة Firebase السحابية" رمز تسجيل من خلال الطريقة messaging:didReceiveRegistrationToken: في FIRMessagingDelegate's. تسترد حزمة تطوير البرامج (SDK) للمراسلة عبر السحابة الإلكترونية من Firebase رمزًا مميّزًا جديدًا أو حاليًا أثناء تشغيل التطبيق لأول مرة و كلما تم تعديل الرمز المميّز أو إبطاله. في جميع الحالات، تستدعي حزمة تطوير البرامج (SDK) للمراسلة عبر السحابة الإلكترونية من Firebase الطريقة messaging:didReceiveRegistrationToken: باستخدام رمز مميّز صالح.

قد يتغيّر رمز التسجيل في الحالات التالية:

• استعادة التطبيق على جهاز جديد
• إلغاء تثبيت التطبيق وإعادة تثبيته
• محو بيانات التطبيق

ضبط مفوّض المراسلة

لتلقّي رموز التسجيل، عليك تنفيذ بروتوكول مفوّض المراسلة وضبط السمة delegate في FIRMessaging's بعد استدعاء [FIRApp configure]. على سبيل المثال، إذا كان مفوّض تطبيقك يتوافق مع بروتوكول مفوّض المراسلة ، يمكنك ضبط المفوّض على application:didFinishLaunchingWithOptions: لنفسه.

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

استرداد رمز التسجيل الحالي

يتم إرسال رموز التسجيل من خلال الطريقة messaging:didReceiveRegistrationToken:. يتم استدعاء هذه الطريقة عادةً مرة واحدة لكل عملية بدء تشغيل تطبيق باستخدام رمز التسجيل. عند استدعاء هذه الطريقة، يكون الوقت مثاليًا لإجراء ما يلي:

• إرسال رمز التسجيل إلى خادم تطبيقك إذا كان جديدًا
• الاشتراك في المواضيع باستخدام رمز التسجيل لا يكون ذلك مطلوبًا إلا للاشتراكات الجديدة أو في الحالات التي أعاد فيها المستخدم تثبيت التطبيق.

يمكنك استرداد الرمز المميّز مباشرةً باستخدام token(completion:). يتم توفير خطأ غير فارغ إذا تعذّر استرداد الرمز المميّز بأي شكل من الأشكال.

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

يمكنك استخدام هذه الطريقة في أي وقت للوصول إلى الرمز المميّز بدلاً من تخزينه.

مراقبة إعادة تحميل الرمز المميّز

لتلقّي إشعار كلما تم تعديل الرمز المميّز، عليك توفير مفوّض يتوافق مع بروتوكول مفوّض المراسلة. يسجِّل المثال التالي المفوّض ويضيف طريقة المفوّض المناسبة:

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

بدلاً من ذلك، يمكنك الاستماع إلى NSNotification باسم kFIRMessagingRegistrationTokenRefreshNotification بدلاً من توفير طريقة مفوّض. تحتوي السمة `token` دائمًا على الرمز المميّز الحالي.

تغيير وظيفة الإجراء غير مفعَّل: ربط رمز إشعارات Apple الفورية (APNs) برمز التسجيل

إذا أوقفت تغيير وظيفة الإجراء أو كنت تُنشئ تطبيق SwiftUI، عليك ربط رمز إشعارات Apple الفورية (APNs) بشكل صريح برمز التسجيل في FCM نفِّذ الطريقة application(_:didRegisterForRemoteNotificationsWithDeviceToken:) لاسترداد رمز إشعارات Apple الفورية (APNs)، ثم اضبط السمة 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;
}

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

منع الإعداد التلقائي

عند إنشاء رمز تسجيل FCM، تحمِّل المكتبة المعرّف وبيانات الإعداد إلى Firebase. إذا أردت الحصول أولاً على موافقة صريحة من المستخدمين، يمكنك منع إنشاء الرمز المميّز في وقت الإعداد من خلال إيقاف "مراسلة Firebase السحابية". لإجراء ذلك، أضِف قيمة بيانات وصفية إلى Info.plist (وليس GoogleService-Info.plist):

FirebaseMessagingAutoInitEnabled = NO

لإعادة تفعيل مراسلة Firebase السحابية، يمكنك إجراء استدعاء في وقت التشغيل:

Messaging.messaging().autoInitEnabled = true

[FIRMessaging messaging].autoInitEnabled = YES;

تظل هذه القيمة ثابتة بعد إعادة تشغيل التطبيق بعد ضبطها.

إعداد إضافة خدمة الإشعارات

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

لإضافة إضافة خدمة، عليك تنفيذ مهام الإعداد المطلوبة لـ تعديل الإشعارات وعرضها في إشعارات Apple الفورية (APNs)، ثم إضافة واجهة برمجة تطبيقات مساعد الإضافة في NotificationService.m. على وجه التحديد، بدلاً من إكمال معاودة الاتصال باستخدام self.contentHandler(self.bestAttemptContent);، أكملها باستخدام FIRMessaging extensionHelper كما هو موضّح:

@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];

}
...

إرسال رسالة إشعار

1. ثبِّت التطبيق وشغِّله على جهاز الاختبار. على أجهزة Apple، اقبَل طلب الإذن بتلقّي الإشعارات عن بُعد.
2. تأكَّد من أنّ التطبيق يعمل في الخلفية على الجهاز.
3. في وحدة تحكّم Firebase، افتح صفحة المراسلة عبر السحابة الإلكترونية.
4. إذا كانت هذه هي رسالتك الأولى، انقر على إنشاء حملتك الأولى.
   1. انقر على رسائل الإشعارات في Firebase ، ثم على إنشاء.
5. بخلاف ذلك، في علامة التبويب الحملات ، انقر على حملة جديدة ، ثم على الإشعارات.
6. أدخِل نص الرسالة.
7. انقر على إرسال رسالة اختبارية من اللوحة اليمنى.
8. في الحقل الذي يحمل العنوان إضافة رمز تسجيل في FCM، أدخِل رمز التسجيل.
9. انقر على اختبار.

بعد النقر على اختبار، من المفترض أن يتلقّى جهاز العميل المستهدَف الإشعار مع تشغيل التطبيق في الخلفية.

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

الخطوات التالية

بعد إكمال خطوات الإعداد، إليك بعض الخيارات للمضي قدمًا في استخدام FCM لمنصات Apple:

• إرسال الرسائل إلى الأجهزة
• تلقّي الرسائل في تطبيق Apple
• إرسال الرسائل إلى المواضيع