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

يوضّح هذا الدليل كيفية البدء باستخدام Firebase Cloud Messaging في تطبيقات عميل Flutter كي تتمكّن من إرسال الرسائل بشكل موثوق.

بناءً على النظام الأساسي الذي تستهدفه، هناك بعض خطوات الإعداد الإضافية المطلوبة التي عليك اتّخاذها.

لنظام التشغيل iOS+‎

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

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

Android

خدمات Google Play

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

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

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

الويب

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

تستخدم واجهة الويب FCM بيانات اعتماد الويب، المعروفة باسم مفاتيح تعريف خادم التطبيق الطوعي (VAPID)، للسماح بطلبات الإرسال إلى خدمات الإشعارات الفورية على الويب المتوافقة. للاشتراك في الإشعارات الفورية، عليك ربط زوج من المفاتيح بمشروع Firebase. يمكنك إما إنشاء زوج مفاتيح جديد أو استيراد زوج المفاتيح الحالي من خلال Firebase وحدة التحكم.

تثبيت مكوّن 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, make sure 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);

تظل هذه القيمة ثابتة بعد إعادة تشغيل التطبيق بعد ضبطها.

إرسال رسالة إشعار اختبارية

1. ثبِّت التطبيق وشغِّله على جهاز الاختبار. على أجهزة Apple، عليك قبول طلب الإذن بتلقّي الإشعارات عن بُعد.

2. تأكَّد من أنّ التطبيق قيد التشغيل في الخلفية على الجهاز.

3. في وحدة تحكّم Firebase، انتقِل إلى DevOps والتفاعل > المراسلة.

4. أنشئ حملة.

   • إذا كانت هذه هي رسالتك الأولى:

     1. انقر على إنشاء حملتك الأولى.

     2. اختَر رسائل الإشعارات في Firebase وانقر على إنشاء.

   • إذا سبق لك إنشاء حملات:

     1. في علامة التبويب الحملات ، انقر على حملة جديدة.

     2. انقر على الإشعارات.

5. أدخِل نص الرسالة.

6. انقر على إرسال رسالة اختبارية من اللوحة اليمنى.

7. في الحقل الذي يحمل العنوان إضافة رمز تسجيل مميّز في FCM، أدخِل رمز التسجيل المميّز.

8. انقر على اختبار.

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

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

معالجة التفاعل

عندما ينقر المستخدمون على إشعار، يكون السلوك التلقائي على كل من Android وiOS هو فتح التطبيق. إذا تم إنهاء التطبيق، سيتم تشغيله، وإذا كان قيد التشغيل في الخلفية، سيتم إظهاره في المقدّمة.

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

توفّر حزمة firebase-messaging طريقتَين لمعالجة هذا التفاعل:

1. getInitialMessage(): إذا تم فتح التطبيق من حالة الإنهاء ، يعرض هذا الإجراء Future يحتوي على RemoteMessage. بعد استخدام ، ستتم إزالة RemoteMessage
2. onMessageOpenedApp: ‏Stream ينشر RemoteMessage عند فتح التطبيق من حالة الخلفية.

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

class Application extends StatefulWidget {
  @override
  State createState() => _Application();
}

class _Application extends State {
  // In this example, suppose that all messages contain a data field with the key 'type'.
  Future setupInteractedMessage() async {
    // Get any messages which caused the application to open from
    // a terminated state.
    RemoteMessage? initialMessage =
        await FirebaseMessaging.instance.getInitialMessage();

    // If the message also contains a data property with a "type" of "chat",
    // navigate to a chat screen
    if (initialMessage != null) {
      _handleMessage(initialMessage);
    }

    // Also handle any interaction when the app is in the background using a
    // Stream listener
    FirebaseMessaging.onMessageOpenedApp.listen(_handleMessage);
  }

  void _handleMessage(RemoteMessage message) {
    if (message.data['type'] == 'chat') {
      Navigator.pushNamed(context, '/chat',
        arguments: ChatArguments(message),
      );
    }
  }

  @override
  void initState() {
    super.initState();

    // Run code required to handle interacted messages in an async function
    // as initState() must not be async
    setupInteractedMessage();
  }

  @override
  Widget build(BuildContext context) {
    return Text("...");
  }
}

تعتمد طريقة معالجة التفاعل على الإعدادات. المثال الذي تم عرضه سابقًا هو مثال أساسي على استخدام StatefulWidget.

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

بعد إكمال خطوات الإعداد، إليك بعض الخيارات للمضي قدمًا في استخدام FCM لـ Flutter:

• إرسال الرسائل إلى الأجهزة
• تلقّي الرسائل في تطبيق Flutter
• إرسال الرسائل إلى المواضيع