إعداد تطبيق عميل "المراسلة عبر السحابة الإلكترونية من Firebase" على Flutter

اتّبِع الخطوات التالية لإعداد برنامج "المراسلة عبر السحابة الإلكترونية من Firebase" على Flutter.

المتطلبات والعملية الخاصة بالنظام الأساسي

تعتمد بعض الخطوات المطلوبة على النظام الأساسي الذي تستهدفه.

iOS+

تفعيل إمكانات التطبيق في Xcode

قبل أن يبدأ تطبيقك في تلقّي الرسائل، يجب تفعيل الإشعارات الفورية وأوضاع الخلفية في مشروع Xcode.

1. افتح مساحة عمل مشروع Xcode (ios/Runner.xcworkspace).
2. فعِّل الإشعارات الفورية.
3. فعِّل وضعَي التنفيذ في الخلفية والإشعارات عن بُعد في الخلفية.

تحميل مفتاح مصادقة أسماء نقاط الوصول (APN)

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

1. في وحدة تحكُّم Firebase ضمن مشروعك، اختَر رمز الترس، ثمّ اختَر إعدادات المشروع (Project Settings)، ثم اختَر علامة التبويب المراسلة عبر السحابة الإلكترونية.
2. اختَر الزر Upload Certificate (تحميل الشهادة) لشهادة التطوير أو شهادة الإنتاج أو كليهما. ويجب إدراج لقطة شاشة واحدة على الأقل.
3. لكل شهادة، اختَر ملف .p12 وأدخِل كلمة المرور، إن وجدت. تأكَّد من أنّ رقم تعريف الحزمة لهذه الشهادة يتطابق مع رقم تعريف حزمة تطبيقك. انقر على حفظ.

طريقة التدوير

لاستخدام المكوّن الإضافي FCM Flutter على أجهزة Apple، يجب عدم إيقاف طريقة التمرير. يجب استخدام Swizzing، وبدونه، لا تعمل ميزات Firebase الأساسية، مثل معالجة الرمز المميّز لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، بشكل صحيح.

Android

خدمات Google Play

يتطلب عملاء FCM أجهزة تعمل بالإصدار 4.4 من نظام التشغيل Android أو إصدار أحدث والتي تم تثبيت خدمات Google Play عليها أيضًا، أو محاكي يعمل بالإصدار 4.4 من نظام التشغيل Android مع واجهات Google APIs. يُرجى ملاحظة أنّه لا تقتصر على نشر تطبيقات Android من خلال "متجر Google Play".

يجب أن تتحقّق التطبيقات التي تعتمد على حزمة تطوير البرامج (SDK) لخدمات Google Play دائمًا من الجهاز بحثًا عن حِزمة APK متوافقة لخدمات Google Play قبل الوصول إلى ميزات خدمات Google Play. ويُنصح بتنفيذ هذا الإجراء في موضعَين: في طريقة onCreate() الخاصة بالنشاط الرئيسي، وطريقة onResume() الخاصة به. يضمن التحقق في "onCreate()" أنّه لا يمكن استخدام التطبيق بدون إجراء عملية فحص ناجحة. تضمن عملية التحقّق onResume() أنّه إذا عاد المستخدم إلى التطبيق قيد التشغيل باستخدام وسائل أخرى، كالنقر على زر الرجوع، سيستمرّ التحقّق من جديد.

إذا لم يكن الجهاز مزوّدًا بإصدار متوافق من "خدمات Google Play"، يمكن لتطبيقك الاتصال بـ GoogleApiAvailability.makeGooglePlayServicesAvailable() للسماح للمستخدمين بتنزيل "خدمات Google Play" من "متجر Play".

الويب

ضبط بيانات اعتماد الويب باستخدام خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"

تستخدم واجهة الويب لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" بيانات اعتماد الويب التي يُطلق عليها "التعريف التطوّعي لخادم التطبيقات" أو مفاتيح "VAPID" للسماح بإرسال طلبات إلى خدمات دفع الويب المتوافقة. ولاشتراك تطبيقك لتلقّي الإشعارات الفورية، عليك ربط مفتاحَين بمشروع Firebase. يمكنك إنشاء مفتاحَي تشفير جديدَين أو استيراد مفتاحَي التشفير الحاليين من خلال وحدة تحكُّم Firebase.

إنشاء مفتاحَي تشفير جديدَين

1. افتح علامة التبويب المراسلة عبر السحابة الإلكترونية في لوحة الإعدادات في وحدة تحكّم Firebase وانتقِل إلى قسم ضبط الويب.

2. في علامة التبويب شهادات Web Push، انقر على إنشاء مفتاحَي تشفير. وتعرِض وحدة التحكّم إشعارًا بأنّه تم إنشاء مفتاحَي التشفير، كما تعرِض سلسلة المفتاح العام وتاريخ الإضافة.

استيراد مفتاحَي تشفير حاليَين

إذا كان لديك مفتاحا تشفير حاليان تستخدمهما حاليًا مع تطبيق الويب، يمكنك استيرادهما إلى خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" لتتمكن من الوصول إلى النُسخ الافتراضية الحالية لتطبيق الويب من خلال واجهات برمجة تطبيقات المراسلة عبر السحابة الإلكترونية من Firebase. لاستيراد المفاتيح، يجب أن يكون لديك إذن وصول على مستوى المالك إلى مشروع Firebase. استورِد المفتاح العام والخاص الحالي في شكل ترميز آمن لعنوان URL الأساسي في base64:

1. افتح علامة التبويب المراسلة عبر السحابة الإلكترونية في لوحة الإعدادات في وحدة تحكّم Firebase وانتقِل إلى قسم ضبط الويب.

2. في علامة التبويب شهادات Web Push، ابحث عن نص الرابط "استيراد مفتاحَي تشفير حاليَين" واختَره.

3. في مربّع الحوار استيراد مفتاحَي تشفير، أدخِل المفاتيح العامة والخاصة في الحقول المقابلة لها، ثم انقر على استيراد. تعرض وحدة التحكم سلسلة المفتاح العام وتاريخ الإضافة.

لمزيد من المعلومات عن تنسيق المفاتيح وكيفية إنشائها، راجِع مفاتيح خادم التطبيقات.

تثبيت المكوّن الإضافي لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase"

1. يمكنك تثبيت مكوّنات Firebase الإضافية لبرنامج Flutter وإعدادها إذا لم يسبق لك إجراء ذلك.

2. من جذر مشروع Flutter، شغِّل الأمر التالي لتثبيت المكوِّن الإضافي:

   flutter pub add firebase_messaging
   

3. بعد إكمال الخطوات، أعِد إنشاء تطبيق Flutter:

   flutter run
   

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

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

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

// You may set the permission requests to "provisional" which allows the user to choose what type
// of notifications they would like to receive once the user receives a notification.
final notificationSettings = await FirebaseMessaging.instance.requestPermission(provisional: true);

// For apple platforms, ensure the APNS token is available before making any FCM plugin API calls
final apnsToken = await FirebaseMessaging.instance.getAPNSToken();
if (apnsToken != null) {
 // APNS token is available, make FCM plugin API requests...
}

على الأنظمة الأساسية للويب، أرسِل مفتاح VAPID العام إلى getToken():

final fcmToken = await FirebaseMessaging.instance.getToken(vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu");

لتلقّي إشعارات عند تعديل الرمز المميّز، اشترِك في ساحة المشاركات onTokenRefresh:

FirebaseMessaging.instance.onTokenRefresh
    .listen((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.
    })
    .onError((err) {
      // Error getting token.
    });

منع الإعداد التلقائي

عند إنشاء رمز مميّز للتسجيل عبر خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، تحمّل المكتبة المعرّف وبيانات الإعداد إلى Firebase. إذا كنت تفضّل منع الإنشاء التلقائي للرموز المميّزة، أوقِف الإعداد التلقائي في وقت الإنشاء.

iOS

على iOS، أضِف قيمة للبيانات الوصفية إلى Info.plist:

FirebaseMessagingAutoInitEnabled = NO

Android

على نظام التشغيل Android، أوقِف جمع "إحصاءات Google" والإعداد التلقائي للمراسلة عبر السحابة الإلكترونية من Firebase (يجب إيقافهما) عن طريق إضافة قيم البيانات الوصفية التالية إلى AndroidManifest.xml:

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />

إعادة تفعيل التشغيل التلقائي للمراسلة عبر السحابة الإلكترونية من Firebase في وقت التشغيل

لتفعيل التشغيل التلقائي لمثيل تطبيق معيّن، يمكنك طلب setAutoInitEnabled():

await FirebaseMessaging.instance.setAutoInitEnabled(true);

تظل هذه القيمة سارية في جميع عمليات إعادة تشغيل التطبيق بعد ضبطها.

الخطوات اللاحقة

بعد الانتهاء من إعداد تطبيق العميل، ستكون جاهزًا لبدء إرسال الرسائل باستخدام خيار إنشاء الإشعارات. راجِع إرسال رسالة اختبار إلى تطبيق في الخلفية.

لإضافة سلوك آخر أكثر تقدّمًا إلى تطبيقك، ستحتاج إلى تنفيذ خادم.

بعد ذلك، ضِمن برنامج تطبيقك:

• تلقّي الرسائل
• الاشتراك في مواضيع الرسائل