عرض مصدر ReactNative/pushnotificationios

<noinclude>{{DISPLAYTITLE:PushNotificatonIOS في React Native}}</noinclude>
<blockquote>'''مهملة'''. استخدم [https://github.com/react-native-community/react-native-push-notification-ios ‎@react-native-community/push-notification-ios] بدلًا منها.</blockquote><blockquote>
====== خاص بالمشاريع المكتوبة بشفرة Native ======
هذه المقالة مطبَّقة على المشاريع المكتوبة بشفرة Native فقط، أما إذا كنت تستخدم سير العمل <code>expo-cli</code> فعليك الاطلاع على الدليل [https://docs.expo.io/versions/latest/sdk/notifications Notifications] ضمن توثيق Expo لإيجاد البديل الملائم.</blockquote>يعالج إشعارات الدّفع (push notifications) في التطبيقات، بما فيها الأذونات ورقم شارة الأيقونة (badge number). يجب [https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/AddingCapabilities/AddingCapabilities.html#//apple_ref/doc/uid/TP40012582-CH26-SW6 إعداد الإشعارات مع Apple] وكذلك النّظام من جانب الخادم  لتهيئتها وتشغيلها.

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

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

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

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

* CocoaPods:
** إضافة مكتبة PushNotificationIOS إلى Podfile على المسار: ‎./ios/Podfile
<syntaxhighlight lang="javascript">
target 'myAwesomeApp' do
  # Pods for myAwesomeApp
  pod 'React-RCTPushNotification', :path => '../node_modules/react-native/Libraries/PushNotificationIOS'
end
</syntaxhighlight>

* [https://reactnative.dev/docs/linking-libraries-ios#manual-linking الرّبط اليدويّ] لمكتبة PushNotificationIOS:
** يجب إضافة ما يلي إلى المشروع: <syntaxhighlight>
node_modules/react-native/Libraries/PushNotificationIOS/RCTPushNotification.xcodeproj
</syntaxhighlight>
** يجب إضافة <code>libRCTPushNotification.a</code> إلى <code>Link Binary With Libraries</code> 

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

في أعلى <code>AppDelegate.m</code>:<syntaxhighlight lang="javascript">
#import <React/RCTPushNotificationManager.h>
</syntaxhighlight>ثمّ يجب إضافة ما يلي إلى AppDelegate المُنشأ:<syntaxhighlight lang="javascript">
// مطلوب من أجل التسجيل للإشعارات
 - (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];
 }
</syntaxhighlight>يجب إضافة السطور البرمجية التالية لإظهار الإشعارات بينما تكون في الواجهة (هذه الخاصّية متوفّرة بدءًا من iOS 10):

* في أعلى الملف <code>AppDelegate.m</code>:<syntaxhighlight lang="javascript">
#import <UserNotifications/UserNotifications.h>
</syntaxhighlight>ثم يجب إضافة ما يلي إلى AppDelegate المُنشأ:<syntaxhighlight lang="javascript">
- (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);
}
</syntaxhighlight>بعدها يمكن تفعيل إشعارات الخلفيّة والإشعارات البعيدة لتستخدم بشكلٍ صحيحٍ. وأسهل طريقة للقيام بذلك هي عن طريق إعدادات المشروع، وذلك بالانتقال إلى Targets ‏-> Your App ‏-> Capabilities‏ -> Background Modes وتأكيد Remote notifications. والذي بدوره يمكٍّن الإعدادات المطلوبة تلقائيًا. 

== التّوابع ==

=== <code>presentLocalNotification()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.presentLocalNotification(details);
</syntaxhighlight>يجدول الإشعارات المحليّة (localNotification) لعرضها مباشرةّ.

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>details</code>
|كائن (object)
|نعم
|انظر أسفل الجدول
|}
يحوي الكائن details ما يلي:

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

=== <code>scheduleLocalNotification()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.scheduleLocalNotification(details);
</syntaxhighlight>يقوم بجدولة localNotification لعرضها مستقبلًا.

==== المعاملات (parameters) ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>details</code>
|كائن (object)
|نعم
|انظر أسفل الجدول
|}
يحوي الكائن details ما يلي:

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

=== <code>cancelAllLocalNotification()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.cancelAllLocalNotifications();
</syntaxhighlight>يلغي جميع localNotification المجدولة.

=== <code>removeAllDeliveredNotifications()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.removeAllDeliveredNotifications();
</syntaxhighlight>يزيل جميع التنبيهات المسلَّمة من مركز التنبيهات.

=== <code>getDeliveredNotifications()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.getDeliveredNotifications(callback);
</syntaxhighlight>يعطي قائمةً بإشعارات التطبيقات التي لا تزال ظاهرةً في مركز الإشعارات.

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>callback</code>
|دالة (function)
|نعم
|دالةٌ تستقبل مصفوفةً من الإشعارات المسلّمة
|}
الإشعار المسلم (delivered notification) هو كائن يحوي ما يلي:

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

=== <code>removeDeliveredNotifications()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.removeDeliveredNotifications(identifiers);
</syntaxhighlight>يزيل الإشعارات المخصّصة من مركز الإشعارات.

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>identifires</code>
|مصفوفة (array)
|نعم
|مصفوفة من معرِّفات الإشعارات
|}

=== <code>setApplicationIconBadgeNumber()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.setApplicationIconBadgeNumber(number);
</syntaxhighlight>يضع رقم شارة (badge number) أيقونة التّطبيق على الشاشة الرئيسية (home screen).

==== المعاملات (parameters) ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>number</code>
|رقم (number)
|نعم
|رقم شارة أيقونة التطبيق
|}

=== <code>getApplicationIconBadgeNumber()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.getApplicationIconBadgeNumber(callback);
</syntaxhighlight>يجلب رقم الشّارة الحاليّ لأيقونة التطبيق على الشاشة الرئيسية (home screen).

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>callback</code>
|دالّة (function)
|نعم
|الدالّة التي سيمرّر لها رقم الشّارة الحاليّ
|}

=== <code>cancelLocalNotifications()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.cancelLocalNotifications(userInfo);
</syntaxhighlight>يلغي جميع الإشعارات المحليَّة، ويمكن بشكلٍ اختياريٍّ تقييده بقائمةٍ من الإشعارات الملغيّة المحدّدة في المُعامل <code>userInfo</code>.

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
|-
|<code>userinfo</code>
|كائن (object)
|لا
|}

=== <code>getScheduledLocalNotifications()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.getScheduledLocalNotifications(callback);
</syntaxhighlight>يجلب الإشعارات المحليَّة والمُجدولة حاليًا.

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب  
!الوصف
|-
|<code>callback</code>
|دالة (function)
|نعم
|الدّالة التي سيمرّر لها مصفوفةً من الكائنات التي تصف الإشعارات المحليّة
|}

=== <code>addEventListener()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.addEventListener(type, handler);
</syntaxhighlight>يُلحِق المراقب (listener) بأحداث الإشعارات المحليّة أو البعيدة عندما يعمل التطبيق في الواجهة أو الخلفيّة.

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>type</code>
|سلسلة نصية (string)
|نعم
|صنف الحدث
|-
|<code>handler</code>
|دالة (function)
|نعم
|المراقب
|}
الأحداث الصّالحة هي:

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

=== <code>removeEventListener()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.removeEventListener(type, handler);
</syntaxhighlight>يزيل معالج الحدَث، ويجب أن يتم ذلك في <code>componentWillUnmount</code> لمنع تسرّب المعلومات من الذاكرة.

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|type
|سلسلة نصية
string
|نعم
|نوع الحدث
|-
|handler
|دالة
function
|نعم
|مراقِب
|}

=== <code>requestPermissions()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.requestPermissions([permissions]);
</syntaxhighlight>يطلب من المستخدم عبر مربع حوار منح أذونات الإشعارات (notification permissions) من منصة iOS. ويطلب جميع أذونات الإشعار بشكلٍ افتراضيٍّ، لكن يمكن أن يطلب مجموعةً فرعيّةً من هذه الأذونات عن طريق تمرير خريطة (map) من الأذونات المطلوبة. وتدعم هذه الدالة الأذونات التالية:

* التنبيه  <code>alert</code>
* الشارة  <code>badge</code>
* الصوت <code>sound</code>

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

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

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>permission</code>
|مصفوفة (array)
|لا
|تنبيه أو شارة أو صوت
|}

=== <code>abandonPermissions()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.abandonPermissions();
</syntaxhighlight>يُستخدم لإلغاء تسجيل جميع الإشعارات البعيدة المستقبلة عن طريق خدمة Apple Push Notification. يُستخدم هذا التابع نادرًا، حيث يُستخدم فقط في حالة قيام الإصدار الجديد من التطبيق بإلغاء دعم جميع الإشعارات البعيدة، عندها يمكن للمستخدم منع التطبيق من استقبال الإشعارات البعيدة بشكلٍ مؤقتٍ عن طريق قسم الإشعارات في إعدادات التطبيق، ويمكن دائمًا إعادة تسجيل التطبيقات التي تم إلغاء تسجيلها بهذه الطريقة. 

=== <code>checkPermissions()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.checkPermissions(callback);
</syntaxhighlight>يُستخدم لرؤية أذونات الدفع (push) المفعّلة حاليًا.

==== المعاملات ====
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|<code>callback</code>
|دالّة (function)
|نعم
|انظر أسفل الجدول
|}
يتم استدعاء <code>callback</code> عن طريق الكائن <code>permissions</code>:

* التنبيه  <code>alert</code> (قيمة منطقيّة)
* الشارة  <code>badge</code> (قيمة منطقيّة)
* الصوت <code>sound</code> (قيمة منطقيّة)

=== <code>getInitialNotification()‎</code> ===
<syntaxhighlight lang="javascript">
PushNotificationIOS.getInitialNotification();
</syntaxhighlight>يُعيد هذا التابع وعدًا، وإذا شغِّل التطبيق عن طريق إشعارات الدفع فإن هذا الوعد يُقبل إلى كائن من النوع <code>PushNotificationIOS</code>، وإلا فإنه يُقبل إلى القيمة <code>null</code>.

=== <code>constructor()‎</code> ===
<syntaxhighlight lang="javascript">
constructor(nativeNotif);
</syntaxhighlight>لن تحتاج أبدًا إلى استنساخ <code>PushNotificationIOS</code> بنفسك، بل يكفي مراقبة الحدث <code>notification</code> واستدعاء <code>getInitialNotification</code>.

=== <code>finish()‎</code> ===
<syntaxhighlight lang="javascript">
finish(fetchResult);
</syntaxhighlight>يتاح هذا التابع للإشعارات البعيدة المستقبلة بواسطة [https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-apphttps://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application?language=objclication?language=objc application:didReceiveRemoteNotification:fetchCompletionHandler:‎] حيث يطلَب للتنفيذ عند الانتهاء من معالجة الإشعار البعيد، ويتم تمرير قيمة ناتج الطلبية fetchResult التي تصف ناتج العملية. ويجب طلب هذا المعالج في أقرب فرصةٍ ممكنةٍ، ويمكن الاطلاع على قائمة القيم الممكنة عن طريق <code>PushNotificationIOS.FetchResult</code>. إن لم يُستدعَى هذا التابع، فمن الممكن حدوث اختناقٍ للإشعارات البعيدة الموجودة في الخلفية.
=== <code>getMessage()‎</code> ===
<syntaxhighlight lang="javascript">
getMessage();
</syntaxhighlight>هو اسمٌ بديلٌ للتابع <code>getAlert</code> ويستخدم للحصول على الرسالة الرئيسية للإشعار.

=== <code>getSound()‎</code> ===
<syntaxhighlight lang="javascript">
getSound();
</syntaxhighlight>يجلب اسم ملف الصوت من الكائن <code>aps</code>.

=== <code>getCategory()‎</code> ===
يجلب فئة الإشعار من الكائن <code>aps</code>.

=== <code>getAlert()‎</code> ===
<syntaxhighlight lang="javascript">
getAlert();
</syntaxhighlight>يجلب رسالة الإشعار الرئيسية من الكائن <code>aps</code>.

=== <code>getContentAvailable()‎</code> ===
<syntaxhighlight lang="javascript">
getContentAvailable();
</syntaxhighlight>يجلب الرقم المتوفر في المحتوى من الكائن <code>aps</code>.

=== <code>getBadgeCount()‎</code> ===
<syntaxhighlight lang="javascript">
getBadgeCount();
</syntaxhighlight>يجلب عدد الشارات من الكائن <code>aps</code>.

=== <code>getData()‎</code> ===
<syntaxhighlight lang="javascript">
getData();
</syntaxhighlight>يجلب كائن المعطيات من الإشعار.

=== <code>getThreadID()‎</code> ===
<syntaxhighlight lang="javascript">
getThreadID();
</syntaxhighlight>يجلب معرِّف المهمّة من الإشعار.

== مصادر ==

* [https://facebook.github.io/react-native/docs/pushnotificationios صفحة PushNotificationIOS في توثيق React Native الرسميّ]
[[تصنيف:ReactNative]]