إشعارات تطبيقك لا تصل إلى آيفون: مفتاح APNs وإعداد Firebase
باختصار: حين تعمل الإشعارات على أندرويد وتفشل على آيفون، فالمشكلة غالباً في الحلقة بين Firebase وخدمة إشعارات آبل APNs، لا في كود الإرسال نفسه. أندرويد يستلم من Firebase مباشرة، أما آيفون فيحتاج أن تسلّم Firebase الرسالة إلى APNs باستخدام مفتاح مصادقة من حساب مطور آبل. افحص بالترتيب: هل رُفع مفتاح APNs بصيغة p8 إلى إعدادات Firebase مع معرّف المفتاح ومعرّف الفريق الصحيحين؟ هل قدرة Push Notifications مفعلة في مشروع Xcode؟ هل وافق المستخدم على الإشعارات؟ هل البيئة صحيحة بين التطوير والإنتاج؟ ثم أرسل رسالة اختبار من لوحة Firebase إلى رمز جهاز محدد لتعزل المشكلة.
كيف تمر الإشعارة إلى آيفون
لفهم مكان العطل، تخيّل المسار:
- التطبيق على آيفون يطلب إذن المستخدم، ثم يسجل لدى APNs، فتعطيه آبل رمز جهاز (device token).
- مكتبة Firebase في التطبيق تربط هذا الرمز برمز FCM خاص بها، وترسله لخادمك.
- خادمك أو لوحة Firebase يرسل الإشعار إلى FCM باستخدام رمز FCM.
- FCM يسلم الإشعار إلى APNs مستخدماً المفتاح الذي رفعته.
- APNs يوصله إلى الجهاز.
أي حلقة مكسورة توقف كل شيء، وغالباً دون رسالة خطأ واضحة للمستخدم. قائمة الفحص التالية تمر على الحلقات بالترتيب.
قائمة الفحص
1. مفتاح APNs وفريق المطور
في حساب Apple Developer، ضمن قسم المفاتيح (Keys)، يُنشأ مفتاح مع تفعيل خدمة Apple Push Notifications، ويُحمّل ملفه بامتداد p8 مرة واحدة فقط. ثم في Firebase Console، من إعدادات المشروع، تبويب Cloud Messaging، قسم إعداد تطبيق Apple، يُرفع الملف مع:
- Key ID: معرّف المفتاح الظاهر في حساب آبل.
- Team ID: معرّف فريق المطور، ويظهر في صفحة العضوية.
أخطاء شائعة هنا:
- المفتاح من حساب آبل مختلف عن الحساب الذي يُنشر منه التطبيق، كأن يكون من حساب المطور الشخصي بينما التطبيق منشور من حساب الشركة.
- Team ID منسوخ خطأً أو لحساب آخر.
- المفتاح أُلغي في حساب آبل بعد رفعه، ربما أثناء تنظيف الحسابات.
- رُفع المفتاح لتطبيق iOS آخر داخل مشروع Firebase نفسه، لا للتطبيق المقصود.
تحقق أيضاً أن Bundle ID المسجل لتطبيق iOS في Firebase يطابق تماماً Bundle ID في Xcode وفي App Store Connect.
2. قدرة Push Notifications في Xcode
في مشروع Xcode، اختر هدف التطبيق، ثم تبويب Signing & Capabilities، وتأكد من وجود:
- Push Notifications: دون هذه القدرة لن يحصل التطبيق على رمز جهاز من APNs.
- Background Modes مع Remote notifications: ضرورية إن كنت ترسل إشعارات صامتة لتحديث البيانات في الخلفية.
إن كان التطبيق مبنياً بـ Flutter أو React Native، فهذه الخطوة تتم أيضاً في مشروع iOS داخل المجلد الخاص به، ويغفلها كثيرون لأنهم يعملون في الكود المشترك فقط.
بعد إضافة القدرة، تأكد أن ملف تعريف التوقيع (provisioning profile) أُعيد توليده ويتضمنها. التوقيع التلقائي في Xcode يعالج ذلك عادة.
3. إذن المستخدم
آيفون لا يعرض أي إشعار مرئي دون موافقة صريحة من المستخدم. تحقق من:
- أن التطبيق يطلب الإذن فعلاً عبر واجهة UNUserNotificationCenter أو ما يقابلها في المكتبة.
- أن الطلب يحدث في لحظة منطقية، لا عند أول فتح قبل أن يفهم المستخدم التطبيق، فكثيرون يرفضون حينها.
- أن جهاز الاختبار لم يرفض سابقاً: افتح الإعدادات، ثم الإشعارات، ثم اسم التطبيق، وتأكد أن "السماح بالإشعارات" مفعل.
- أن وضع التركيز أو عدم الإزعاج ليس مفعلاً على جهاز الاختبار.
وإن رفض المستخدم، فلا يمكن للتطبيق إعادة إظهار نافذة النظام. اعرض له شاشة تشرح الفائدة مع زر يفتح إعدادات التطبيق.
4. بيئة التطوير والإنتاج
APNs لها بيئتان: تطوير (sandbox) وإنتاج. التطبيق المثبت من Xcode مباشرة يستخدم بيئة التطوير، والتطبيق من TestFlight أو App Store يستخدم الإنتاج.
- مع مفتاح p8 تعمل المصادقة للبيئتين، وهذه ميزة كبيرة مقارنة بالشهادات القديمة.
- إن كان مشروعك ما زال يستخدم شهادات p12، فلكل بيئة شهادة، وكثيراً ما تُرفع شهادة التطوير فقط، فتعمل الإشعارات في الاختبار وتتوقف بعد النشر. الانتقال إلى مفتاح p8 يحل هذا.
- رمز الجهاز يختلف بين البيئتين. لا تختبر برمز نسخة Xcode على نسخة TestFlight.
5. ربط رمز APNs برمز FCM
مكتبة Firebase تربط الرمزين تلقائياً عبر آلية تسمى method swizzling. إن عطّلها المطور لسبب ما، فيجب تمرير رمز APNs إلى Firebase يدوياً في الكود. علامة هذه المشكلة: التطبيق يحصل على رمز FCM، لكن الإشعارات لا تصل أبداً إلى آيفون. توثيق Firebase لإعداد عميل iOS يشرح الحالتين.
الاختبار من لوحة Firebase
لتعزل المشكلة عن خادمك:
- أضف في التطبيق مؤقتاً سطراً يطبع رمز FCM في سجل Xcode، أو يعرضه في شاشة مخفية للمطورين.
- افتح Firebase Console، ثم قسم Messaging، وأنشئ حملة إشعار جديدة.
- اختر "إرسال رسالة اختبار" والصق رمز FCM.
- أغلق التطبيق أو ضعه في الخلفية، فالإشعار المرئي لا يظهر بالشكل المعتاد والتطبيق مفتوح في المقدمة ما لم تعالجه في الكود.
إن وصلت رسالة الاختبار ولم تصل رسائل خادمك، فالمشكلة في طريقة الإرسال من الخادم: ربما يرسل رسالة بيانات فقط دون محتوى مرئي، أو يستخدم واجهة قديمة، أو رمزاً قديماً. وإن لم تصل رسالة الاختبار أيضاً، فارجع إلى الخطوات 1 إلى 5.
اختبر على جهاز حقيقي
اختبار الإشعارات على جهاز آيفون حقيقي هو الأكثر موثوقية، وبالنسخة نفسها التي سيستخدمها الناس عبر TestFlight. سجّل لكل اختبار: إصدار iOS، مصدر التثبيت، حالة الإذن، رمز FCM، والنتيجة.
أسئلة شائعة
الإشعارات تصل لبعض مستخدمي آيفون فقط، لماذا؟
على الأرجح هؤلاء وافقوا على الإذن والآخرون لم يوافقوا، أو أن بعض الرموز المخزنة في خادمك قديمة لأجهزة حُذف منها التطبيق. نظّف الرموز التي تعيد أخطاء عند الإرسال.
هل نحتاج مفتاح p8 جديداً لكل تطبيق؟
مفتاح واحد يمكن استخدامه لعدة تطبيقات في حساب المطور نفسه، لكن احفظه في مكان آمن تملكه الشركة، لأنه لا يُحمّل مرة ثانية.
كانت الإشعارات تعمل ثم توقفت فجأة؟
راجع إن كان المفتاح أُلغي في حساب آبل، أو تغير Bundle ID، أو انتهت عضوية حساب المطور.
إن كانت إشعارات تطبيقك صامتة على آيفون وتحتاج من يتتبع الحلقة المكسورة، أرسل لنا وصف الإعداد الحالي.