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

اتّبِع الخطوات التالية لإعداد عميل FCM على Flutter.

الإعدادات والمتطلبات الخاصة بالمنصة

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

iOS+‎

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

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

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

تحميل مفتاح مصادقة APNs

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

  1. داخل مشروعك في "وحدة تحكّم Firebase"، انقر على رمز الترس، ثم على إعدادات المشروع، ثم على علامة التبويب Cloud Messaging.
  2. انقر على الزر تحميل الشهادة لشهادة التطوير أو شهادة الإنتاج أو كلتيهما. يجب توفُّر لقطة شاشة واحدة على الأقل.
  3. لكل شهادة، اختَر ملف ‎ .p12 وقدِّم كلمة المرور، إذا كانت مطلوبة. تأكَّد من أنّ رقم تعريف الحزمة لهذه الشهادة يطابق رقم تعريف الحزمة لتطبيقك، ثم انقر على حفظ.

تغيير وظيفة الإجراء

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

Android

خدمات Google Play

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

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

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

الويب

ضبط بيانات اعتماد الويب باستخدام FCM

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

إنشاء زوج مفاتيح جديد

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

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

استيراد زوج مفاتيح حالي

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

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

  2. في علامة التبويب شهادات الإشعارات الفورية على الويب، ابحث عن نص الرابط "استيراد زوج مفاتيح حالي" وانقر عليه.

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

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

تثبيت المكوّن الإضافي لخدمة FCM

  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.
    });

منع بدء التشغيل التلقائي

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

iOS

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

FirebaseMessagingAutoInitEnabled = NO

Android

على أجهزة Android، أوقِف جمع البيانات في "إحصاءات Google" والإعداد التلقائي لخدمة FCM (يجب إيقاف كليهما) من خلال إضافة قيم البيانات الوصفية التالية إلى 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" />

إعادة تفعيل ميزة "التهيئة التلقائية" في FCM في وقت التشغيل

لتفعيل ميزة "بدء التشغيل التلقائي" لمثيل تطبيق معيّن، استخدِم الرمز setAutoInitEnabled():

await FirebaseMessaging.instance.setAutoInitEnabled(true);

تظل هذه القيمة محفوظة عند إعادة تشغيل التطبيق بعد ضبطها.

الخطوات التالية

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

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

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