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


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

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

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

iOS+‎

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

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

Android

خدمات Google Play

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

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

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

الويب

ضبط Web Credentials باستخدام 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، افتح صفحة "المراسلة".
  4. إذا كانت هذه هي رسالتك الأولى، اختَر إنشاء حملتك الأولى.
    1. اختَر رسائل إشعارات Firebase، ثمّ انقر على إنشاء.
  5. بخلاف ذلك، في علامة التبويب الحملات، انقر على حملة جديدة، ثم على الإشعارات.
  6. أدخِل نص الرسالة.
  7. اختَر إرسال رسالة اختبار من اللوحة اليمنى.
  8. في الحقل الذي يحمل التصنيف إضافة رمز مميّز للتسجيل في FCM، أدخِل رمز التسجيل.
  9. انقر على اختبار.

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

للحصول على إحصاءات حول وصول الرسائل إلى تطبيقك، اطّلِع على لوحة بيانات FCM التي تسجّل عدد الرسائل المرسَلة والمفتوحة على أجهزة 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: