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

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

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

iOS+‎

تبديل الطرق

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

Android

خدمات Google Play

تتطلب أجهزة عملاء FCM نظام التشغيل Android 7.0 أو إصدارًا أحدث، بالإضافة إلى تثبيت خدمات Google Play، أو محاكيًا يعمل بنظام التشغيل Android 7.0 مع واجهات 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 بيانات اعتماد الويب التي تُعرف باسم Voluntary Application Server Identification أو مفاتيح VAPID، وذلك للسماح بطلبات الإرسال إلى خدمات الإشعارات الفورية على الويب المتوافقة. للاشتراك في الإشعارات الفورية، عليك ربط زوج من المفاتيح بمشروع Firebase. يمكنك إما إنشاء مفتاحا تشفير جديدين أو استيراد مفتاحا التشفير الحاليين من خلال Firebase وحدة التحكّم.

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

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

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

   flutter pub add firebase_messaging
   

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

   flutter run
   

طلب إذن إرسال الإشعارات

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

// 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...
}

الوصول إلى رقم تعريف عملية التثبيت في Firebase

تفعيل التسجيل باستخدام رقم تعريف عملية التثبيت في Firebase

لتفعيل تسجيل نُسخة تطبيقك في خدمة FCM باستخدام رقم تعريف عملية التثبيت في Firebase (FID)، عليك أولاً تفعيل أرقام تعريف عمليات التثبيت في إعدادات تطبيقك لمنصّتَي Android وApple (لا يلزم إجراء إعدادات ثابتة للموافقة في الويب):

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

<key>FirebaseMessagingInstallationIdEnabled</key>
<true/>

الاشتراك في مصدر البيانات onRegistered

لإرسال رسالة إلى نُسخة تطبيقك على جهاز معيّن، تحتاج إلى رقم تعريف عملية التثبيت في Firebase (FID) لنُسخة التطبيق هذه بعد تسجيلها في FCM. يتم تسليم FID بشكل غير متزامن من خلال مصدر البيانات onRegistered.

على منصّتَي Android وApple، FCM تسجِّل نُسخة التطبيق تلقائيًا عند بدء التشغيل عندما يكون الإعداد التلقائي مفعّلاً (الإعداد التلقائي). ومع ذلك، يجب إجراء طلب صريح إلى register():

• على الويب : يمكنك اختياريًا تمرير vapidKey وserviceWorkerScriptPath.
• على منصّتَي Android وApple إذا كان الإعداد التلقائي غير مفعّل أو بعد استدعاء unregister(). يمكنك أيضًا استدعاء register() في أي وقت لتشغيل onRegistered باستخدام مهلة الاستجابة الأولى (FID) المسجَّلة من قبل.

احرِص دائمًا على الاشتراك في onRegistered قبل استدعاء register() لكي يكون المستمع نشطًا عند إرسال حدث التسجيل:

final messaging = FirebaseMessaging.instance;

messaging.onRegistered
    .listen((String installationId) {
      // TODO: Send the Firebase Installation ID (FID) to your application server.
    })
    .onError((err) {
      // Error getting Firebase Installation ID.
    });

// Required on Web, and on Android/Apple if auto-initialization is disabled.
await messaging.register(
  // Optional on Web (ignored on Android and Apple platforms)
  vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu",
);

يرسل مصدر البيانات onRegistered رقم تعريف عملية التثبيت في الحالات التالية:

1. تلقائيًا عند بدء تشغيل التطبيق لأول مرة والمزامنة الروتينية على منصّتَي Android وApple عندما يكون الإعداد التلقائي مفعّلاً
2. في كل مرة يكتمل فيها استدعاء register() يدويًا (حتى إذا كانت نُسخة التطبيق مسجَّلة من قبل، سيظل onRegistered يرسل رقم تعريف عملية التثبيت المسجَّل من قبل)
3. عندما يتم رصد تغيير في رقم تعريف عملية التثبيت في Firebase وإعادة تسجيل التطبيق في FCM، أو على الويب عند إطلاق pushsubscriptionchange حدث

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

الوصول إلى رمز التسجيل المميّز (متوقّف نهائيًا)

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

على منصّات الويب، مرِّر مفتاح 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. إذا كنت تفضّل منع التسجيل التلقائي، أوقِف الإعداد التلقائي في وقت الإنشاء.

عند إيقاف الإعداد التلقائي، يمكنك تسجيل نُسخة التطبيق بشكل صريح في وقت التشغيل من خلال استدعاء register() (احرِص على الاشتراك في onRegistered أولاً لتلقّي رقم تعريف عملية التثبيت في Firebase):

await FirebaseMessaging.instance.register();

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" />

إعادة تفعيل الإعداد التلقائي لـ FCM في وقت التشغيل

لتفعيل الإعداد التلقائي لنُسخة تطبيق معيّنة، استدعِ setAutoInitEnabled():

await FirebaseMessaging.instance.setAutoInitEnabled(true);

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

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

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

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

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

4. أنشئ حملة.

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

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

     2. انقر على إشعارات Firebase ، ثم على إنشاء.

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

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

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

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

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

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

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
• إرسال الرسائل إلى المواضيع