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

اتّبِع الخطوات التالية لإعداد عميل خدمة "إشعارات من Google‏ (FCM)" على Flutter.

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

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

iOS+

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

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

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

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

قبل استخدام "خدمة إرسال الرسائل إلى الأجهزة الجوّالة من Google"، حمِّل شهادة APNs إلى Firebase. إذا لم يكن لديك شهادة APNs، أنشئ شهادة في Apple Developer Member Center.

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

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

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

Android

خدمات Google Play

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

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

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

الويب

ضبط بيانات اعتماد الويب باستخدام "Firebase Cloud Messaging"

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

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

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

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

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

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

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

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

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

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

تثبيت المكوّن الإضافي لنظام إرسال الرسائل من Google Cloud Messaging

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

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

    flutter pub add firebase_messaging

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

    flutter run

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

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

لاسترداد الرمز المميّز الحالي للتسجيل لمثيل تطبيق، اتصل بالرقم 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" وإعداد 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);

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

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

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

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

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