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

// 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 & Engagement > المراسلة.

4. أنشئ حملة.

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

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

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

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

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

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

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

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

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

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

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

للحصول على إحصاءات حول عملية تسليم الرسائل إلى تطبيقك، انتقِل إلى لوحة بيانات DevOps & Engagement > المراسلة > التقارير في وحدة تحكّم 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
• إرسال الرسائل إلى المواضيع