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

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

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

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

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

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

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

تحميل مفتاح مصادقة APNs

حمِّل مفتاح مصادقة APNs إلى Firebase. إذا لم يكن لديك مفتاح مصادقة APNs، احرص على إنشاء مفتاح في مركز أعضاء Apple Developer.

1. في وحدة تحكّم "Firebase"، انتقِل إلى settings الإعدادات > إعدادات عامة. بعد ذلك، انقر على علامة التبويب خدمة المراسلة عبر السحابة الإلكترونية.
2. في مفتاح مصادقة APNs ضمن إعدادات تطبيق iOS، انقر على تحميل لتحميل مفتاح مصادقة التطوير أو مفتاح مصادقة الإنتاج أو كليهما. ويجب توفير طريقة اتصال واحدة على الأقل.
3. انتقِل إلى الموقع الذي حفظت فيه مفتاحك، واختَره، ثم انقر على فتح. أضِف معرّف المفتاح (المتوفّر في مركز أعضاء مطوّري Apple) وانقر على تحميل.

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

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

الوصول إلى معرّف Firebase Installation ID

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

بالطريقة نفسها التي توفّر بها منصات Apple عادةً رمزًا مميزًا لجهاز APNs عند بدء تشغيل التطبيق، يوفّر FCM معرّف FID لاستهداف الإشعارات. توفّر حزمة تطوير البرامج (SDK) لخدمة FCM معرّف FID باستخدام طريقة messaging:didReceiveRegistration: في FIRMessagingDelegate، وتراقب تلقائيًا تغييرات معرّف FID، وتستدعي الطريقة باستخدام معرّف FID جديد عند رصد تغيير. ننصحك باسترداد معرّف FID وتحميله بانتظام لأنّه يمكن أن يتغيّر بعد بدء التشغيل الأوّلي.

تفعيل التسجيل باستخدام معرّف تثبيت Firebase

لتفعيل تسجيل مثيل تطبيقك في "FCM" باستخدام رقم تعريف تثبيت Firebase (FID)، أضِف علامة البيانات الوصفية التالية إلى ملف Info.plist، وليس ملف GoogleService-Info.plist:

FirebaseMessagingInstallationIdEnabled = YES

ضبط المفوَّض لإرسال الرسائل

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

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

تنفيذ طريقة didReceiveRegistration

يتم استهداف نُسخ التطبيق باستخدام معرّف مثيل Firebase بعد اكتمال عملية التسجيل. لتلقّي معرّف FID عند التسجيل، نفِّذ الطريقة messaging:didReceiveRegistration:. يتم عادةً استدعاء هذه الطريقة مرة واحدة لكل عملية بدء للتطبيق باستخدام معرّف FID. عند استدعاء هذه الطريقة، يمكنك تنفيذ الإجراءات التالية:

• إذا لم تكن قد أرسلت معرّف FID إلى الخادم أو أرسلته مؤخرًا، أرسِله إلى خادم التطبيق.
• إذا كان الاشتراك جديدًا أو أعاد المستخدم تثبيت التطبيق، اشترِك في المواضيع باستخدام معرّف مثيل Firebase.

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

التسجيل يدويًا عند إيقاف الإعداد التلقائي

في حال إيقاف الإعداد التلقائي، لن تسجِّل حزمة تطوير البرامج (SDK) لخدمة FCM تلقائيًا مثيل التطبيق في FCM عند بدء تشغيل التطبيق. يجب استدعاء register عند بدء تشغيل التطبيق لتفعيل التسجيل وتسليم معرّف Firebase من خلال طريقة 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: ربط رمز APNs وFID

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

بعد تسجيل معرّف FID، يمكنك الوصول إليه والاستماع إلى أحداث إعادة التحميل باستخدام الطرق نفسها المتّبعة عند تفعيل طريقة swizzling.

الوصول إلى رمز التسجيل المميّز (متوقّف نهائيًا)

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

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

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

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

ضبط المفوَّض لإرسال الرسائل

لتلقّي رموز التسجيل، عليك تنفيذ بروتوكول تفويض المراسلة وضبط السمة delegate في FIRMessaging بعد طلب [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 بدلاً من توفير طريقة تفويض. تحتوي سمة الرمز المميّز دائمًا على قيمة الرمز المميّز الحالية.

تم إيقاف Swizzling: ربط الرمز المميّز لخدمة APNs والرمز المميّز للتسجيل

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

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

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

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

FirebaseMessagingAutoInitEnabled = NO

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

Messaging.messaging().autoInitEnabled = true

[FIRMessaging messaging].autoInitEnabled = YES;

وتظل هذه القيمة محفوظة عند إعادة تشغيل التطبيق بعد ضبطها.

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

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

لإضافة إضافة خدمة، عليك تنفيذ مهام الإعداد المطلوبة لتعديل الإشعارات وعرضها في APNs، ثم إضافة واجهة برمجة التطبيقات المساعدة لإضافة FCM في 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، انتقِل إلى DevOps & Engagement > المراسلة

4. أنشئ حملة.

   • إذا كانت هذه رسالتك الأولى:

     1. انقر على إنشاء حملتك الأولى.

     2. اختَر رسائل إشعارات Firebase، ثمّ انقر على إنشاء.

   • إذا سبق لك إنشاء حملات:

     1. في علامة التبويب الحملات، انقر على حملة جديدة.

     2. انقر على الإشعارات.

5. أدخِل نص الرسالة.

6. انقر على إرسال رسالة اختبار من اللوحة اليسرى.

7. في الحقل الذي يحمل التصنيف إضافة معرّف تثبيت Firebase أو FCM رمز التسجيل المميّز، أدخِل رمز التسجيل المميّز.

8. اختَر اختبار.

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

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

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

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

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