ReactNative/pushnotificationios

مهملة: استخدم إحدى الحزم من المجتمع بدلًا منها.

خاص بالمشاريع المكتوبة بشفرة Native هذه المقالة مطبَّقة على المشاريع المكتوبة بشفرة Native فقط، أمّا إذا كنت تستخدم سير العمل expo-cli فعليك الاطلاع على الدليل Notifications ضمن توثيق Expo لإيجاد البديل الملائم.

يعالج إشعارات الدّفع (push notifications) في التطبيقات، بما فيها الأذونات، ورقم شارة الأيقونة (badge number)، حيث يجب إعداد الإشعارات مع Apple، وكذلك النّظام من جانب الخادم لتهيئتها، وتشغيلها.

في إصدارات React Native 0.60.0، وما بعده:

• تقوم خاصّية الرّبط التّلقائيّ Autolinking بالتّكفّل بعمليّة الربّط.

أما في إصدارات React Native السابقة للإصدار 0.60.0، فيجب:

• إضافة مكتبة PushNotificationIOS إلى Podfile على المسار: ‎./ios/Podfile

• CocoaPods:
  • إضافة مكتبة PushNotificationIOS إلى Podfile على المسار: ‎./ios/Podfile

target 'myAwesomeApp' do
  # Pods for myAwesomeApp
  pod 'React-RCTPushNotification', :path => '../node_modules/react-native/Libraries/PushNotificationIOS'
end

• الرّبط اليدويّ لمكتبة PushNotificationIOS:
  • يجب إضافة ما يلي إلى المشروع:

    node_modules/react-native/Libraries/PushNotificationIOS/RCTPushNotification.xcodeproj
    

  • يجب إضافة ما يلي إلى Link Binary With Libraries: libRCTPushNotification.a

وأخيرًا يجب إكمال AppDelegate لتمكين الدّعم للأحداث notification، وregister، وذلك كما يلي:

في أعلى AppDelegate.m:

#import <React/RCTPushNotificationManager.h>

ثمّ يجب إضافة ما يلي إلى AppDelegate المُنشأ:

// مطلوب من أجل التسجيل للإشعارات
 - (void)application:(UIApplication *)application didRegisterUserNotificationSettings:(UIUserNotificationSettings *)notificationSettings
 {
  [RCTPushNotificationManager didRegisterUserNotificationSettings:notificationSettings];
 }
 // register مطلوب من أجل حدَث التسجيل
 - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
 {
  [RCTPushNotificationManager didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
 }
 // notification مطلوب من أجل حدَث الإشعارات  
 // يجب طلب معالج الإكمال قبل معالجة الإشعارات البعيدة   
 - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
                                                        fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
 {
   [RCTPushNotificationManager didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
 }
 // registrationError مطلوب من أجل الحدَث
 - (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
 {
  [RCTPushNotificationManager didFailToRegisterForRemoteNotificationsWithError:error];
 }
 // localNotification مطلوب من أجل الحدَث
 - (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification
 {
  [RCTPushNotificationManager didReceiveLocalNotification:notification];
 }

يجب إضافة السطور البرمجية التالية لإظهار الإشعارات بينما تكون في الواجهة (هذه الخاصّية متوفّرة بدءًا من iOS 10):

• في أعلى الملف AppDelegate.m:

#import <UserNotifications/UserNotifications.h>

ثم يجب إضافة ما يلي إلى AppDelegate المُنشأ:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  ...
  // UNUserNotificationCenter تعريف 
  UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
  center.delegate = self;
​
  return YES;
}
​
//  تستدعى عند تسليم الإشعار إلى التطبيق الذي في الواجهة
-(void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
{
  completionHandler(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge);
}

بعدها يمكن تفعيل إشعارات الخلفيّة والإشعارات البعيدة لتستخدم بصورة صحيحة. وأسهل طريقة للقيام بذلك هي عن طريق إعدادات المشروع، وذلك بالانتقال إلى Targets ‏-> Your App ‏-> Capabilities‏ -> Background Modes وتأكيد Remote notifications، والذي بدوره يمكٍّن الإعدادات المطلوبة تلقائيًا.

التوابع

presentLocalNotification()‎

PushNotificationIOS.presentLocalNotification(details);

يجدول الإشعارات المحليّة (localNotification) لعرضها مباشرةً.

المعاملات:

الاسم	النوع	مطلوب	الوصف
details	كائن (object)	نعم	انظر أسفل الجدول

يحوي الكائن details ما يلي:

• alertBody: الرسالة الظّاهرة في منبِّه الإشعار.
• alertAction: الإجراء "action" الظاهر أسفل الإشعار الفعّال، وبشكلٍ افتراضيٍّ تكون الواجهة "view" التي ألغتها Apple في الإصدار iOS 10، وما بعده.
• alertTitle: النّصّ الذي يظهر كعنوانٍ لمنبّه الإشعار.
• soundName: الصّوت الذي سيشغّل عند إطلاق الإشعار (اختياريّ).
• isSilent: سيظهر الإشعار من دون صوتٍ، إذا كانت قيمته true (اختياريّ).
• category: فئة الإشعار (اختياريّ).
• userInfo: كائنٌ يحتوي على معلوماتٍ إضافيّةٍ عن الإشعار (اختياريّ).
• applicationIconBadgeNumber: الرقم الذي سيظهر مثل إشارةٍ لأيقونة التّطبيق. والقيمة 0 هي القيمة الافتراضيّة مما يعني أنه لن تظهر أيّ إشارةٍ (اختياريّ).

scheduleLocalNotification()‎

PushNotificationIOS.scheduleLocalNotification(details);

يقوم بجدولة localNotification لعرضها مستقبلًا.

المعاملات:

الاسم	النوع	مطلوب	الوصف
details	كائن (object)	نعم	انظر أسفل الجدول

يحوي الكائن details ما يلي:

• fireDate: الوقت والتاريخ الذي سيقوم فيه النظام بتسليم الإشعار.
• alertTitle: النص الذي يظهر كعنوانٍ لمنبّه الإشعار.
• alertBody: الرّسالة التي ستعرض في منبِّه الإشعار.
• alertAction: الإجراء "action" الظاهر أسفل الإشعار الفعّال، وبشكلٍ افتراضيٍّ تكون الواجهة "view" الذي قد ألغته Apple في الإصدار iOS 10 وما بعده.
• soundName: الصوت الذي سيشغل عند إطلاق الإشعار (اختياريّ).
• isSilent: سيظهر الإشعار من دون صوتٍ إذا كان true (اختياريّ).
• category: فئة الإشعار (اختياريّ).
• userInfo: كائن يحتوي على معلوماتٍ إضافيّةٍ عن الإشعار (اختياريّ).
• applicationIconBadgeNumber: الرقم الذي سيظهر كإشارةٍ لأيقونة التطبيق. والقيمة 9 هي القيمة الافتراضيّة مما يعني أنه لن تظهر أيّ إشارةٍ (اختياريّ).
• repeatInterval: الفاصل الزمنيّ للتكرار، ويكون سلسلةً نصيةً مثل: minute, hour, day, week, month, year (اختياريّ).

cancelAllLocalNotification()‎

PushNotificationIOS.cancelAllLocalNotifications();

يلغي جميع localNotification المجدولة.

removeAllDeliveredNotifications()‎

PushNotificationIOS.removeAllDeliveredNotifications();

يزيل جميع التنبيهات المسلَّمة من مركز التنبيهات.

getDeliveredNotifications()‎

PushNotificationIOS.getDeliveredNotifications(callback);

يعطي قائمةً بإشعارات التطبيقات التي لا تزال ظاهرةً في مركز الإشعارات.

المعاملات:

الاسم	النوع	مطلوب	الوصف
callback	دالة (function)	نعم	دالةٌ تستقبل مصفوفةً من الإشعارات المسلّمة

الإشعار المسلم (delivered notification) هو كائن يحوي ما يلي:

• identifier: معرِّف هذا الإشعار.
• title: عنوان هذا الإشعار.
• body: جسم هذا الإشعار.
• category: فئة هذا الإشعار (اختياريّ).
• userInfo: كائنٌ يحتوي على معلوماتٍ إضافيّةٍ عن الإشعار (اختياريّ).
• thread-id: معرِّف عمليّة (thread) هذا الإشعار إن وجِدَت.

removeDeliveredNotifications()‎

PushNotificationIOS.removeDeliveredNotifications(identifiers);

يزيل الإشعارات المخصّصة من مركز الإشعارات.

المعاملات:

الاسم	النوع	مطلوب	الوصف
identifires	مصفوفة (array)	نعم	مصفوفة من معرِّفات الإشعارات

setApplicationIconBadgeNumber()‎

PushNotificationIOS.setApplicationIconBadgeNumber(number);

يضع رقم شارة (badge number) أيقونة التّطبيق على الشاشة الرئيسية (home screen).

المعاملات:

الاسم	النوع	مطلوب	الوصف
number	عدد (number)	نعم	رقم شارة أيقونة التطبيق

getApplicationIconBadgeNumber()‎

PushNotificationIOS.getApplicationIconBadgeNumber(callback);

يجلب رقم الشّارة الحاليّ لأيقونة التطبيق على الشاشة الرئيسية (home screen).

المعاملات:

الاسم	النوع	مطلوب	الوصف
callback	دالّة (function)	نعم	الدالّة التي سيمرّر لها رقم الشّارة الحاليّ

cancelLocalNotifications()‎

PushNotificationIOS.cancelLocalNotifications(userInfo);

يلغي جميع الإشعارات المحليَّة، ويمكن بشكلٍ اختياريٍّ تقييده بقائمةٍ من الإشعارات الملغيّة المحدّدة في المُعامل userInfo.

المعاملات:

الاسم	النوع	مطلوب
userinfo	كائن (object)	لا

getScheduledLocalNotifications()‎

PushNotificationIOS.getScheduledLocalNotifications(callback);

يجلب الإشعارات المحليَّة والمُجدولة حاليًا.

المعاملات

الاسم	النوع	مطلوب	الوصف
callback	دالة (function)	نعم	الدّالة التي سيمرّر لها مصفوفةً من الكائنات التي تصف الإشعارات المحليّة

addEventListener()‎

PushNotificationIOS.addEventListener(type, handler);

يُلحِق المراقب (listener) بأحداث الإشعارات المحليّة أو البعيدة عندما يعمل التطبيق في الواجهة أو الخلفيّة.

المعاملات:

الاسم	النوع	مطلوب	الوصف
type	سلسلة نصية (string)	نعم	صنف الحدث
handler	دالة (function)	نعم	المراقب

الأحداث الصّالحة هي:

• notification: يُطلَق عند استقبال الإشعار البعيد، حيث يستدعى المُعالج عن طريق نسخةٍ من PushNotificationIOS.
• localNotification: يُطلَق عند استقبال الإشعار المحليّ، حيث يستدعى المعالج عن طريق نسخةٍ من PushNotificationIOS.
• register: يُطلق عندما يسجل المستخدم من أجل الإشعارات البعيدة، حيث يستدعى المُعالج عن طريق مقطعٍ نصيٍّ يمثّل رمز الجهاز (deviceToken).
• registrationError: يُطلق عندما يفشل المستخدم في التسجيل من أجل الإشعارات البعيدة، ويحصل ذلك عادة عند وجود مشاكل في APNS، أو أنّ الجهاز عبارة عن محاكٍ. ويُستدعَى المعالج مع {message: string, code: number, details: any}.

removeEventListener()‎

PushNotificationIOS.removeEventListener(type, handler);

يزيل معالج الحدَث، ويجب أن يتم ذلك في componentWillUnmount لمنع تسرّب المعلومات من الذاكرة.

المعاملات:

الاسم	النوع	مطلوب	الوصف
type	سلسلة نصية (string)	نعم	نوع الحدث
handler	دالة (function)	نعم	مراقِب

requestPermissions()‎

PushNotificationIOS.requestPermissions([permissions]);

يطلب من المستخدم عبر مربع حوار منح أذونات الإشعارات (notification permissions) من منصة iOS. ويطلب جميع أذونات الإشعار بشكلٍ افتراضيٍّ، لكن يمكن أن يطلب مجموعةً فرعيّةً من هذه الأذونات عن طريق تمرير خريطة (map) من الأذونات المطلوبة. وتدعم هذه الدالة الأذونات التالية:

• التنبيه alert
• الشارة badge
• الصوت sound

وإذا مرّرت خريطة الأذونات إلى التابع فإنه لا يطلب إلا الأذونات ذات القيمة المنطقية true.

ويعيد هذا التابع وعدًا (promise) والذي يُقبل (resolve) عند قيام المستخدم بقبول الأذونات أو رفضها أو إذا رفضت الأذونات مسبقًا، سيقبل الوعد إلى الحالة الحالية للأذونات.

المعاملات:

الاسم	النوع	مطلوب	الوصف
permission	مصفوفة (array)	لا	تنبيه أو شارة أو صوت

abandonPermissions()‎

PushNotificationIOS.abandonPermissions();

يُستخدم لإلغاء تسجيل جميع الإشعارات البعيدة المستقبلة عن طريق خدمة Apple Push Notification. يُستخدم هذا التابع نادرًا، حيث يُستخدم فقط في حالة قيام الإصدار الجديد من التطبيق بإلغاء دعم جميع الإشعارات البعيدة، عندها يمكن للمستخدم منع التطبيق من استقبال الإشعارات البعيدة بشكلٍ مؤقتٍ عن طريق قسم الإشعارات في إعدادات التطبيق، ويمكن دائمًا إعادة تسجيل التطبيقات التي تم إلغاء تسجيلها بهذه الطريقة.

checkPermissions()‎

PushNotificationIOS.checkPermissions(callback);

يُستخدم لرؤية أذونات الدفع (push) المفعّلة حاليًا.

المعاملات

الاسم	النوع	مطلوب	الوصف
callback	دالّة (function)	نعم	انظر أسفل الجدول

يتم استدعاء callback عن طريق الكائن permissions:

• التنبيه alert (قيمة منطقيّة)
• الشارة badge (قيمة منطقيّة)
• الصوت sound (قيمة منطقيّة)

getInitialNotification()‎

PushNotificationIOS.getInitialNotification();

يُعيد هذا التابع وعدًا، وإذا شغِّل التطبيق عن طريق إشعارات الدفع فإن هذا الوعد يُقبل إلى كائن من النوع PushNotificationIOS، وإلا فسيُقبل إلى القيمة null.

constructor()‎

constructor(nativeNotif);

لن تحتاج أبدًا إلى استنساخ PushNotificationIOS بنفسك، بل يكفي مراقبة الحدث notification واستدعاء getInitialNotification.

finish()‎

finish(fetchResult);

يتاح هذا التابع للإشعارات البعيدة المستقبلة بواسطة application:didReceiveRemoteNotification:fetchCompletionHandler:‎ حيث يطلَب للتنفيذ عند الانتهاء من معالجة الإشعار البعيد، ويتم تمرير قيمة ناتج الطلبية fetchResult التي تصف ناتج العملية. ويجب طلب هذا المعالج في أقرب فرصةٍ ممكنةٍ، ويمكن الاطلاع على قائمة القيم الممكنة عن طريق PushNotificationIOS.FetchResult. إن لم يُستدعَى هذا التابع، فمن الممكن حدوث اختناقٍ للإشعارات البعيدة الموجودة في الخلفية.

getMessage()‎

getMessage();

هو اسمٌ بديلٌ للتابع getAlert ويستخدم للحصول على الرسالة الرئيسية للإشعار.

getSound()‎

getSound();

يجلب اسم ملف الصوت من الكائن aps.

getCategory()‎

يجلب فئة الإشعار من الكائن aps.

getAlert()‎

getAlert();

يجلب رسالة الإشعار الرئيسية من الكائن aps.

getContentAvailable()‎

getContentAvailable();

يجلب الرقم المتوفر في المحتوى من الكائن aps.

getBadgeCount()‎

getBadgeCount();

يجلب عدد الشارات من الكائن aps.

getData()‎

getData();

يجلب كائن المعطيات من الإشعار.

getThreadID()‎

getThreadID();

يجلب معرِّف المهمّة من الإشعار.

مصادر

• صفحة PushNotificationIOS في توثيق React Native الرسميّ