1. مقدمة
تاريخ آخر تعديل: 6-1-2020
Firebase Cloud Messaging (FCM) هو حلّ للمراسلة على مستوى جميع الأنظمة الأساسية يتيح لك إرسال الرسائل بشكل موثوق بدون أي تكلفة.
باستخدام FCM، يمكنك إرسال إشعار إلى تطبيق العميل بأنّه تتوفّر رسالة إلكترونية جديدة أو بيانات أخرى يمكن مزامنتها. يمكنك إرسال رسائل إشعارات لتشجيع المستخدمين على إعادة التفاعل والاحتفاظ بهم. بالنسبة إلى حالات الاستخدام، مثل المراسلة الفورية، يمكن أن تنقل الرسالة حمولة تصل إلى 4 كيلوبايت إلى تطبيق العميل.
كيف تعمل هذه الميزة؟
يتضمّن تنفيذ FCM مكوّنَين رئيسيَّين للإرسال والاستلام:
- بيئة موثوق بها، مثل "وظائف Firebase السحابية" أو خادم تطبيق يمكنك من خلاله إنشاء الرسائل واستهدافها وإرسالها
- تطبيق عميل iOS أو Android أو الويب (JavaScript) يتلقّى الرسائل من خلال خدمة النقل الخاصة بالنظام الأساسي المعنيّ.
نظرة عامة على بنية "المراسلة عبر السحابة الإلكترونية من Firebase"
تعتمد خدمة FCM على مجموعة المكوّنات التالية التي تنشئ الرسائل وتنقلها وتتلقّاها:
- أدوات لإنشاء طلبات الرسائل أو إنشائها توفّر أداة إنشاء الإشعارات خيارًا مستندًا إلى واجهة المستخدم الرسومية لإنشاء طلبات الإشعارات. للحصول على التشغيل الآلي الكامل وإتاحة جميع أنواع الرسائل، يجب إنشاء طلبات الرسائل في بيئة خادم موثوقة تتوافق مع حزمة تطوير البرامج (SDK) الخاصة بـ Firebase Admin أو بروتوكولات خادم FCM. يمكن أن تكون هذه البيئة "وظائف السحابة الإلكترونية لبرنامج Firebase" أو Google App Engine أو خادم التطبيق الخاص بك.
- تتضمّن هذه الخدمة الخلفية (من بين وظائف أخرى) قبول طلبات الرسائل، وتنفيذ عملية توزيع الرسائل على نطاق واسع من خلال المواضيع، وإنشاء البيانات الوصفية للرسائل، مثل معرّف الرسالة.
- طبقة نقل على مستوى النظام الأساسي، تعمل على توجيه الرسالة إلى الجهاز المستهدف، وتتولّى عملية تسليم الرسالة، وتطبّق الإعدادات الخاصة بالنظام الأساسي عند الاقتضاء. تتضمّن طبقة النقل ما يلي:
- طبقة النقل في Android (ATL) لأجهزة Android التي تتضمّن "خدمات Google Play"
- خدمة الإشعارات الفورية من Apple (APNs) لأجهزة iOS
- بروتوكول الإشعارات الفورية على الويب لتطبيقات الويب
- حزمة تطوير البرامج (SDK) الخاصة بخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" على جهاز المستخدم، حيث يتم عرض الإشعار أو معالجة الرسالة وفقًا لحالة التطبيق في المقدّمة أو الخلفية وأي منطق تطبيق ذي صلة
ما ستنشئه
في هذه الدراسة التطبيقية حول الترميز، ستضيف إشعارات فورية إلى نموذج تطبيق iOS باستخدام FCM.
ما ستتعلمه
- كيفية الاشتراك في خدمة الرسائل الفورية وإلغاء الاشتراك فيها
- كيفية التعامل مع الرسائل الفورية الواردة
- كيفية عرض إشعار
- كيفية الردّ على نقرات الإشعارات
المتطلبات
- الإصدار 11.0 من Xcode أو إصدار أحدث
- CocoaPods 1.9.0 أو إصدار أحدث
- حساب المطوّر على Apple
- جهاز iOS فعلي لتشغيل تطبيقك
- معرفة أساسية بلغة Swift
2. الإعداد
تنزيل الرمز النموذجي
في هذا الدرس العملي، ستنشئ تطبيقًا اختباريًا خاصًا بك، ولكن إذا أردت الاطّلاع على نموذج التطبيق الحالي وتشغيله، يمكنك تنزيل رمز نموذج التشغيل السريع.
هناك طريقتان للحصول على العيّنة:
- استنسِخ مستودع Git:
$ git clone https://github.com/firebase/quickstart-ios.git
- نزِّل ملف ZIP:
إذا نزّلت المصدر كملف ZIP، سيؤدي فك ضغطه إلى إنشاء مجلد أساسي quickstart-ios
.
إنشاء تطبيق جديد
أنشئ تطبيقًا تجريبيًا خاصًا بك باتّباع الخطوات التالية (الخطوات أدناه متوافقة مع الإصدار 12.3 من XCode):
- افتح XCode وانقر على Create a new Xcode project (إنشاء مشروع Xcode جديد).
- اختَر التطبيق وانقر على التالي.
- أدخِل اسم المنتج (مثل MessagingExample)
- اختَر الفريق (إذا لم تكن قد أنشأت فريقًا، يمكنك إعداده في حسابك على Apple Developer).
- أدخِل معرّف المؤسسة (مثلاً
com.
your-name
) - أدخِل معرّف الحزمة (مثلاً
com.
your-name
.MessagingExample
، يجب أن يكون فريدًا بين جميع تطبيقات iOS). - انقر على لوحة العرض في القائمة المنسدلة الواجهة.
- اختَر مفوض تطبيق UIKit في القائمة المنسدلة دورة الحياة.
- اختَر Swift في اللغة.
- انقر على التالي.
ستحتاج إلى معرّف الحزمة عند إنشاء مفتاح APN وتسجيل تطبيقك في مشروعك على Firebase.
3- إعدادات اسم نقطة الوصول
إنشاء مفتاح المصادقة
يوضّح هذا القسم كيفية إنشاء مفتاح مصادقة لمعرّف تطبيق مفعّل لإشعارات الدفع. إذا كان لديك مفتاح حالي، يمكنك استخدامه بدلاً من إنشاء مفتاح جديد.
لإنشاء مفتاح مصادقة، اتّبِع الخطوات التالية:
- في حساب المطوِّر، انتقِل إلى الشهادات والمعرّفات والملفات الشخصية (Certificates, Identifiers & Profiles)، ثم انتقِل إلى المفاتيح (Keys).
- انقر على زر الإضافة (+) في أعلى يسار الصفحة.
- أدخِل وصفًا لمفتاح مصادقة APNs
- ضِمن "الخدمات الرئيسية"، ضَع علامة في مربّع الاختيار APNs، ثم انقر على متابعة.
- انقر على تسجيل ثم على تنزيل. احفظ مفتاحك في مكان آمن. هذا التنزيل لمرة واحدة، ولا يمكن استرداد المفتاح لاحقًا.
إنشاء معرّف تطبيق
رقم تعريف التطبيق هو معرّف يحدّد التطبيق بشكلٍ فريد، ويتم تمثيله عادةً بنطاق معكوس.
- انتقِل إلى Apple Developer Member Center وسجِّل الدخول.
- انتقِل إلى الشهادات والمعرّفات والملفات الشخصية.
- انتقِل إلى المعرّفات.
- انقر على الزر + لإنشاء معرّف تطبيق جديد.
- اختَر زر الاختيار معرّفات التطبيقات، ثم انقر على متابعة.
- اختَر التطبيق، وانقر على متابعة.
- لإنشاء معرّف التطبيق الجديد، اتّبِع الخطوات التالية:
- أدخِل اسمًا لمعرّف التطبيق.
- أدخِل رقم تعريف الفريق. يجب أن تتطابق هذه القيمة مع معرّف الفريق في علامة التبويب "العضوية".
- في قسم لاحقة رقم تعريف التطبيق، اختَر رقم تعريف التطبيق الواضح، ثم أدخِل معرّف الحزمة.
- في قسم خدمات التطبيقات، تأكَّد من وضع علامة في المربّع بجانب الإشعارات الفورية.
- انقر على متابعة وتأكَّد من صحة المعلومات التي أدخلتها:
- يجب أن تتطابق قيمة المعرّف مع تسلسل قيمتَي معرّف الفريق ومعرّف الحزمة.
- يجب أن تكون الإشعارات الفورية قابلة للإعداد
- انقر على تسجيل لإنشاء رقم تعريف التطبيق.
إنشاء الملف التجاري
لاختبار تطبيقك أثناء تطويره، تحتاج إلى ملف شخصي خاص بالتطوير لمنح أجهزتك الإذن بتشغيل تطبيق لم يتم نشره بعد على App Store.
- انتقِل إلى Apple Developer Member Center وسجِّل الدخول.
- انتقِل إلى الشهادات والمعرّفات والملفات الشخصية.
- في القائمة المنسدلة في أعلى يمين الشاشة، اختَر iOS وtvOS وwatchOS إذا لم تكن هذه الأنظمة محدّدة، ثم انتقِل إلى الملفات الشخصية.
- انقر على الزر + لإنشاء ملف شخصي جديد.
- اختَر تطوير تطبيقات iOS كنوع ملف الإعداد، ثمّ انقر على متابعة.
- في القائمة المنسدلة، اختَر معرّف التطبيق الذي تريد استخدامه، ثم انقر على متابعة.
- اختَر شهادة تطوير iOS الخاصة بمعرّف التطبيق الذي اخترته في الخطوة السابقة، ثم انقر على متابعة.
- اختَر أجهزة iOS التي تريد تضمينها في ملف الإعداد، ثم انقر على متابعة. احرص على اختيار جميع الأجهزة التي تريد استخدامها في الاختبار.
- أدخِل اسمًا لملف الإعداد هذا (مثل MessagingExampleProfile)، ثم انقر على إنشاء.
- انقر على تنزيل لحفظ ملف Provisioning Profile على جهاز Mac.
- انقر مرّتين على ملف "ملف الإعداد" لتثبيته.
4. إضافة Firebase إلى مشروع iOS
إنشاء مشروع على Firebase
قبل أن تتمكّن من إضافة Firebase إلى تطبيق iOS، عليك إنشاء مشروع على Firebase للربط بتطبيق iOS. انتقِل إلى مقالة التعرّف على مشاريع Firebase لمعرفة المزيد عن مشاريع Firebase.
- في "وحدة تحكّم Firebase"، انقر على إضافة مشروع، ثم اختَر اسم مشروع أو أدخِله.
إذا كان لديك مشروع حالي على Google Cloud Platform (GCP)، يمكنك اختيار المشروع من القائمة المنسدلة لإضافة موارد Firebase إليه.
- (اختياري) إذا كنت بصدد إنشاء مشروع جديد، يمكنك تعديل رقم تعريف المشروع.
تخصّص Firebase تلقائيًا رقم تعريف فريدًا لمشروعك على Firebase. انتقِل إلى مقالة "التعرّف على مشاريع Firebase" للتعرّف على كيفية استخدام Firebase لرقم تعريف المشروع.
- انقر على متابعة.
- يمكنك إعداد "إحصاءات Google" لمشروعك، ما يتيح لك الحصول على أفضل تجربة باستخدام أيّ من منتجات Firebase التالية:
- Firebase Crashlytics
- توقعات Firebase
- المراسلة عبر السحابة الإلكترونية من Firebase
- المراسلة داخل تطبيق Firebase
- الإعداد عن بُعد في Firebase
- اختبار A/B من Firebase
عندما يُطلب منك ذلك، اختَر استخدام حساب حالي على "إحصاءات Google" أو إنشاء حساب جديد. إذا اخترت إنشاء حساب جديد، اختَر موقع إعداد التقارير في "إحصاءات Google"، ثمّ اقبل إعدادات مشاركة البيانات وبنود "إحصاءات Google" لمشروعك.
- انقر على إنشاء مشروع (أو إضافة Firebase، إذا كنت تستخدم مشروعًا حاليًا على Google Cloud Platform).
توفّر Firebase تلقائيًا موارد لمشروعك على Firebase. عند اكتمال العملية، سيتم نقلك إلى صفحة النظرة العامة لمشروعك على Firebase في وحدة تحكّم Firebase.
تسجيل تطبيقك في Firebase
بعد إنشاء مشروع على Firebase، يمكنك إضافة تطبيق iOS إليه.
يمكنك الانتقال إلى مقالة التعرّف على مشاريع Firebase لمعرفة المزيد عن أفضل الممارسات والاعتبارات عند إضافة تطبيقات إلى مشروع على Firebase، بما في ذلك كيفية التعامل مع عدة صيغ للإنشاء.
- انتقِل إلى "وحدة تحكّم Firebase".
- في وسط صفحة نظرة عامة على المشروع، انقر على رمز iOS لبدء سير عمل الإعداد.
إذا سبق لك إضافة تطبيق إلى مشروعك على Firebase، انقر على "إضافة تطبيق" لعرض خيارات المنصّة.
- أدخِل معرّف حزمة تطبيقك في حقل معرّف حزمة iOS.
- (اختياري) أدخِل معلومات أخرى عن التطبيق: الاسم المختصر للتطبيق والمعرّف في App Store.
- انقر على تسجيل التطبيق.
إضافة ملف إعداد Firebase
- انقر على تنزيل ملف GoogleService-Info.plist للحصول على ملف إعداد Firebase iOS (
GoogleService-Info.plist
). - انقل ملف الإعداد إلى جذر مشروع Xcode. إذا طُلب منك ذلك، اختَر إضافة ملف الإعداد إلى جميع الأهداف.
إذا كان لديك عدّة معرّفات حِزم في مشروعك، يجب ربط كل معرّف حزمة بتطبيق مسجّل في وحدة تحكّم Firebase لكي يكون لكل تطبيق ملف GoogleService-Info.plist
خاص به.
أغلِق XCode.
إضافة حِزم تطوير البرامج (SDK) لمنصة Firebase إلى تطبيقك
ننصحك باستخدام CocoaPods لتثبيت مكتبات Firebase. ومع ذلك، إذا كنت تفضّل عدم استخدام CocoaPods، يمكنك دمج أُطر عمل حزمة تطوير البرامج (SDK) مباشرةً أو استخدام الإصدار التجريبي من Swift Package Manager.
- أنشِئ Podfile في حال عدم توفّره. إذا كنت تستخدم نموذج التشغيل السريع، سيكون مشروع Xcode وPodfile (مع وحدات Pod) متوفّرَين.
$ cd MessagingExample $ pod init
- أضِف إلى ملف Podfile مجموعات Firebase التي تريد استخدامها في تطبيقك.
يمكنك إضافة أيّ من منتجات Firebase المتوافقة إلى تطبيق iOS.
في نموذج التشغيل السريع، تمت إضافة حِزمتَي تطوير البرامج (SDK) لكلّ من "إحصاءات Google" و"المراسلة عبر السحابة الإلكترونية من Firebase".
# Add the Firebase pod for Google Analytics pod 'Firebase/Analytics' # Add the pod for Firebase Cloud Messaging pod 'Firebase/Messaging'
- ثبِّت وحدات Pod، ثم افتح ملف
.xcworkspace
للاطّلاع على المشروع في Xcode:
$ pod install
- افتح
MessagingExample.xcworkspace
، ثم انقر على التالي في وحدة تحكّم Firebase.
إعداد Firebase في تطبيقك
عليك إضافة رمز إعداد Firebase إلى تطبيقك.
استورِد وحدة Firebase وأعِدّ مثيلاً مشتركًا (في نموذج التشغيل السريع، يتم استيراد وحدة Firebase تلقائيًا).
- استورِد وحدة Firebase في
UIApplicationDelegate
:
AppDelegate.swift
import UIKit
import Firebase // Add this line
- اضبط مثيلاً مشتركًا من FirebaseApp، عادةً في طريقة
application:didFinishLaunchingWithOptions:
لتطبيقك:
AppDelegate.swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
FirebaseApp.configure() // Add this line
return true
}
- انقر على التالي في وحدة تحكّم Firebase.
- تتم إضافة حِزم تطوير البرامج (SDK) من Firebase إلى تطبيقك. انقر على متابعة إلى وحدة التحكّم.
5- ضبط عميل "المراسلة عبر السحابة الإلكترونية من Firebase"
تحميل مفتاح مصادقة APNs
حمِّل مفتاح مصادقة APNs إلى Firebase.
- داخل مشروعك في "وحدة تحكّم Firebase"، انقر على رمز الترس، ثم على إعدادات المشروع، ثم على علامة التبويب Cloud Messaging.
- في مفتاح مصادقة APNs ضمن إعداد تطبيق Apple، انقر على الزر تحميل لتحميل مفتاح مصادقة التطوير أو مفتاح مصادقة الإنتاج أو كليهما. ويجب إدراج أيٍّ منها على الأقل.
- انتقِل إلى الموقع الجغرافي الذي حفظت فيه المفتاح، واختَره، ثم انقر على فتح. أضِف معرّف المفتاح (المتوفّر في الشهادات والمعرّفات والملفات الشخصية في Apple Developer Member Center) وانقر على تحميل.
التسجيل في تلقّي الإشعارات عن بُعد
سجِّل تطبيقك لتلقّي الإشعارات عن بُعد إما عند بدء التشغيل أو في النقطة المطلوبة في مسار تطبيقك.
في نموذج البدء السريع، تمت إضافة registerForRemoteNotifications
.
AppDelegate.swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
FirebaseApp.configure()
// [START register for remote notifications]
if #available(iOS 10.0, *) {
// For iOS 10 display notification (sent via APNS)
UNUserNotificationCenter.current().delegate = self
let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
UNUserNotificationCenter.current().requestAuthorization(options: authOptions, completionHandler: {_, _ in })
} else {
let settings: UIUserNotificationSettings = UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil)
application.registerUserNotificationSettings(settings)
}
application.registerForRemoteNotifications()
// [END register for remote notifications]
return true
}
عيِّن السمة المفوضة UNUserNotificationCenter
من خلال إضافة هذه الأسطر في نهاية ملف AppDelegate.swift.
AppDelegate.swift
@available(iOS 10, *)
extension AppDelegate : UNUserNotificationCenterDelegate {
// Receive displayed notifications for iOS 10 devices.
func userNotificationCenter(_ center: UNUserNotificationCenter,
willPresent notification: UNNotification,
withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
let userInfo = notification.request.content.userInfo
// Print full message.
print(userInfo)
// Change this to your preferred presentation option
completionHandler([[.alert, .sound]])
}
func userNotificationCenter(_ center: UNUserNotificationCenter,
didReceive response: UNNotificationResponse,
withCompletionHandler completionHandler: @escaping () -> Void) {
let userInfo = response.notification.request.content.userInfo
// Print full message.
print(userInfo)
completionHandler()
}
}
تعيين مفوّض المراسلة
لتلقّي رموز التسجيل المميزة، نفِّذ بروتوكول تفويض المراسلة واضبط السمة delegate
الخاصة بـ FIRMessaging
بعد استدعاء [FIRApp configure]
. على سبيل المثال، إذا كان وكيل تطبيقك يتوافق مع بروتوكول وكيل المراسلة، يمكنك ضبط الوكيل على application:didFinishLaunchingWithOptions:
على نفسه (في نموذج التشغيل السريع، تم ضبطه مسبقًا).
AppDelegate.swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
FirebaseApp.configure()
Messaging.messaging().delegate = self // Add this line
// [START register for remote notifications]
if #available(iOS 10.0, *) {
// For iOS 10 display notification (sent via APNS)
UNUserNotificationCenter.current().delegate = self
let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
UNUserNotificationCenter.current().requestAuthorization(options: authOptions, completionHandler: {_, _ in })
} else {
let settings: UIUserNotificationSettings = UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil)
application.registerUserNotificationSettings(settings)
}
application.registerForRemoteNotifications()
// [END register for remote notifications]
return true
}
عيِّن السمة المفوضة FIRMessaging
من خلال إضافة هذه الأسطر في نهاية ملف AppDelegate.swift.
AppDelegate.swift
extension AppDelegate : MessagingDelegate {
func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
print("Firebase registration token: \(String(describing: fcmToken))")
let dataDict:[String: String] = ["token": fcmToken ?? ""]
NotificationCenter.default.post(name: Notification.Name("FCMToken"), object: nil, userInfo: dataDict)
}
}
إضافة إمكانات
لقد أضفت إمكانية "الإشعارات الفورية" في قسم "إنشاء معرّف تطبيق"، ولكن عليك أيضًا إضافة هذه الإمكانية على XCode باتّباع الخطوات التالية (الخطوات أدناه هي في XCode 12.3):
- انقر على اسم المشروع في "مساحة المستكشف" (Navigator Area).
- انقر على التوقيع والإمكانات.
- انقر على + إمكانية.
- انقر مرّتين على أوضاع التشغيل في الخلفية.
- انقر على + إمكانية مرة أخرى.
- انقر مرّتين على الإشعارات الفورية.
- ضَع علامة في المربّع بجانب الإشعارات عن بُعد في قسم أوضاع التشغيل في الخلفية.
6. إرسال رسالة إشعار
يمكنك إرسال رسالة اختبار باتّباع الخطوات التالية:
- ثبِّت التطبيق وشغِّله على الجهاز المستهدف. يجب قبول طلب الإذن بتلقّي الإشعارات عن بُعد.
- احصل على رمز التسجيل في سجلّ XCode.
- تأكَّد من تشغيل التطبيق في الخلفية على الجهاز.
- افتح أداة إنشاء الإشعارات واختَر إشعار جديد.
- أدخِل نص الرسالة.
- انقر على إرسال رسالة اختبارية.
- في الحقل الذي يحمل التصنيف إضافة رمز مميّز للتسجيل في FCM، أدخِل رمز التسجيل الذي حصلت عليه في الخطوة 2.
- انقر على اختبار.
بعد النقر على اختبار، من المفترض أن يتلقّى جهاز العميل المستهدَف (الذي يعمل فيه التطبيق في الخلفية) الإشعار في مركز الإشعارات.
للحصول على إحصاءات حول تسليم الرسائل إلى تطبيقك، اطّلِع على لوحة بيانات إعداد التقارير في FCM التي تسجّل عدد الرسائل المُرسَلة والمفتوحة على أجهزة iOS وAndroid.
7. تهانينا
تهانينا، لقد أرسلت رسالة تجريبية بنجاح.
تتوفّر العديد من الدوال والإعدادات الأخرى في FCM، مثل الاشتراك في المواضيع.
يمكنك الاطّلاع على مستند المطوّرين الرسمي إذا كنت مهتمًا بها.
ما هي الخطوات التالية؟
يمكنك الاطّلاع على بعض هذه الدروس البرمجية.