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

اختيار المنصة: ‫iOS+ Android الويب Flutter Unity C++‎


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

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

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

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

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

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

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

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

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

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

إما عند بدء التشغيل أو في النقطة المطلوبة في مسار تطبيقك، سجِّل تطبيقك لتلقّي الإشعارات عن بُعد. استدعِ الدالة registerForRemoteNotifications كما هو موضّح أدناه:

Swift

UNUserNotificationCenter.current().delegate = self

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

application.registerForRemoteNotifications()

Objective-C

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

[application registerForRemoteNotifications];

الوصول إلى معرّف التثبيت في Firebase

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

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

للحصول على تفاصيل حول الحالات التي يتم فيها إعادة إصدار معرّفات التثبيت في Firebase وكيفية تتبُّعها يدويًا، اطّلِع على تتبُّع دورة حياة معرّف التثبيت في Firebase.

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

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

FirebaseMessagingInstallationIdEnabled = YES

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

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

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

تنفيذ الطريقة didReceiveRegistration

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

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

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

التسجيل يدويًا عند إيقاف ميزة "الإعداد التلقائي"

إذا أوقفت عملية التهيئة التلقائية، لن تسجِّل حزمة تطوير البرامج (SDK) الخاصة بـ FCM مثيل التطبيق تلقائيًا في FCM عند بدء تشغيل التطبيق. يجب طلب الرقم register عند بدء تشغيل التطبيق لتفعيل التسجيل وتسليم المعرّف FID من خلال الطريقة 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.");
}];

إيقاف ميزة Swizzling: ربط رمز APNs وFID

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

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

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

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

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

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

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

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

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

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

منع بدء التشغيل التلقائي

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

FirebaseMessagingAutoInitEnabled = NO

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

Swift

Messaging.messaging().autoInitEnabled = true

Objective-C

[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، انتقِل إلى عمليات تطوير البرامج وإشراك المستخدمين > المراسلة

  4. أنشئ حملة.

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

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

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

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

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

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

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

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

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

  8. انقر على اختبار.

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

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

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

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