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

اختيار المنصة: iOS+ Android Web Flutter Unity C++


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

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

إعداد حزمة تطوير البرامج (SDK)

أضِف Firebase إلى مشروع Android الخاص بك، في حال لم يسبق لك إجراء ذلك.

للحصول على أفضل تجربة مع FCM، ننصحك بشدة بتفعيل Google Analytics في مشروعك. Google Analytics مطلوبة لإعداد تقارير تسليم الرسائل في FCM .

تعديل بيان تطبيقك

أضِف ما يلي إلى بيان تطبيقك:

  • خدمة توسّع FirebaseMessagingService هذه الخدمة مطلوبة إذا أردت إجراء أي معالجة للرسائل بخلاف تلقّي الإشعارات على التطبيقات في الخلفية. لتلقّي الإشعارات في التطبيقات التي تعمل في المقدّمة، وتلقّي حمولة البيانات، وغير ذلك، عليك توسيع هذه الخدمة.
    • <service
    android:name=".java.MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>
    AndroidManifest.xml
  • (اختياري) ضمن مكوّن التطبيق، عناصر بيانات وصفية لضبط رمز إشعار ولون تلقائيَين يستخدم Android هذه القيم عندما لا تحدّد الرسائل الواردة رمزًا أو لونًا بشكل صريح.
    • <!-- Set custom default icon. This is used when no icon is set for incoming notification messages.
     See README(https://goo.gl/l4GJaQ) for more. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_stat_ic_notification" />
<!-- Set color used with incoming notification messages. This is used when no color is set for the incoming
     notification message. See README(https://goo.gl/6BKBk7) for more. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/colorAccent" />
    AndroidManifest.xml
  • (اختياري) بدءًا من Android 8.0 (مستوى واجهة برمجة التطبيقات 26) والإصدارات الأحدث، يتم دعم قنوات الإشعارات ويُنصح باستخدامها. FCM توفّر قناة إشعارات تلقائية تتضمّن إعدادات أساسية. إذا كنت تفضّل إنشاء قناة تلقائية خاصة بك واستخدامها، اضبط default_notification_channel_id على رقم تعريف عنصر قناة الإشعارات كما هو موضّح. ستستخدم FCM هذه القيمة عندما لا تحدّد الرسائل الواردة قناة إشعارات بشكل صريح. قناة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إدارة قنوات الإشعارات. 
    • <meta-data
    android:name="com.google.firebase.messaging.default_notification_channel_id"
    android:value="@string/default_notification_channel_id" />
    AndroidManifest.xml

طلب إذن إرسال الإشعارات أثناء التشغيل على Android 13 والإصدارات الأحدث

يقدّم Android 13 إذنًا جديدًا أثناء التشغيل لعرض الإشعارات. ويؤثر ذلك في جميع التطبيقات التي تعمل على Android 13 أو إصدار أحدث والتي تستخدم FCM إشعارات.

تتضمّن حزمة تطوير البرامج (SDK) من FCM (الإصدار 23.0.6 أو إصدار أحدث) إذن POST_NOTIFICATIONS المحدّد في البيان بشكل تلقائي. ومع ذلك، سيحتاج تطبيقك أيضًا إلى طلب إصدار هذا الإذن أثناء التشغيل باستخدام الثابت android.permission.POST_NOTIFICATIONS. لن يُسمح لتطبيقك بعرض الإشعارات إلى أن يمنح المستخدم هذا الإذن.

لطلب إذن التشغيل الجديد:

Kotlin

// Declare the launcher at the top of your Activity/Fragment:
private val requestPermissionLauncher = registerForActivityResult(
    ActivityResultContracts.RequestPermission(),
) { isGranted: Boolean ->
    if (isGranted) {
        // FCM SDK (and your app) can post notifications.
    } else {
        // TODO: Inform user that that your app will not show notifications.
    }
}

private fun askNotificationPermission() {
    // This is only necessary for API level >= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
            PackageManager.PERMISSION_GRANTED
        ) {
            // FCM SDK (and your app) can post notifications.
        } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
            // TODO: display an educational UI explaining to the user the features that will be enabled
            //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
            //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
            //       If the user selects "No thanks," allow the user to continue without notifications.
        } else {
            // Directly ask for the permission
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
        }
    }
}
MainActivity.kt

Java

// Declare the launcher at the top of your Activity/Fragment:
private final ActivityResultLauncher<String> requestPermissionLauncher =
        registerForActivityResult(new ActivityResultContracts.RequestPermission(), isGranted -> {
            if (isGranted) {
                // FCM SDK (and your app) can post notifications.
            } else {
                // TODO: Inform user that that your app will not show notifications.
            }
        });

private void askNotificationPermission() {
    // This is only necessary for API level >= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
                PackageManager.PERMISSION_GRANTED) {
            // FCM SDK (and your app) can post notifications.
        } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
            // TODO: display an educational UI explaining to the user the features that will be enabled
            //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
            //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
            //       If the user selects "No thanks," allow the user to continue without notifications.
        } else {
            // Directly ask for the permission
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS);
        }
    }
}
MainActivity.java

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

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

أذونات الإشعارات للتطبيقات التي تستهدف Android 12L (المستوى 32 من واجهة برمجة التطبيقات) أو إصدارًا أقدم

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

  • إذا أنشأ تطبيقك أول قناة إشعارات له أثناء تشغيله في الخلفية، وهو ما تفعله حزمة تطوير البرامج (SDK) من FCM عند تلقّي إشعار من FCM، لن يسمح Android بعرض الإشعار ولن يطلب من المستخدم إذن إرسال الإشعارات إلى أن يتم فتح تطبيقك في المرة التالية. يعني ذلك أنّه سيتم فقدان أي إشعارات يتم تلقّيها قبل فتح تطبيقك وقبل أن يمنح المستخدم الإذن.
  • ننصحك بشدة بتعديل تطبيقك ليصبح يستهدف Android 13 والإصدارات الأحدث للاستفادة من واجهات برمجة التطبيقات الخاصة بالمنصة لطلب الإذن. إذا لم يكن ذلك ممكنًا، يجب أن ينشئ تطبيقك قنوات إشعارات قبل إرسال أي إشعارات إلى التطبيق من أجل تفعيل مربّع حوار إذن إرسال الإشعارات والتأكّد من عدم فقدان أي إشعارات. يمكنك الاطّلاع على أفضل ممارسات إذن إرسال الإشعارات لمزيد من المعلومات.

(اختياري) إزالة إذن POST_NOTIFICATIONS

تتضمّن حزمة تطوير البرامج (SDK) من FCM إذن POST_NOTIFICATIONS بشكل تلقائي. إذا كان تطبيقك لا يستخدم رسائل الإشعارات (سواءً من خلال FCM إشعارات، أو من خلال حزمة تطوير برامج (SDK) أخرى، أو من خلال نشرها مباشرةً من قِبل تطبيقك) ولا تريد أن يتضمّن تطبيقك الإذن، يمكنك إزالته باستخدام العلامة remove في أداة دمج البيان. يُرجى العِلم أنّ إزالة هذا الإذن تمنع عرض جميع الإشعارات، وليس فقط إشعارات FCM أضِف ما يلي إلى ملف بيان تطبيقك:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" tools:node="remove"/>

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

عند بدء تشغيل تطبيقك لأول مرة، تنشئ حزمة تطوير البرامج (SDK) من FCM رمز تسجيل لمثيل تطبيق العميل. إذا أردت استهداف مثيلات تطبيق فردية أو إنشاء مجموعات أجهزة، عليك الوصول إلى هذا الرمز المميّز من خلال توسيع FirebaseMessagingService وتجاوز onNewToken. بما أنّه يمكن تدوير الرمز المميّز بعد بدء التشغيل الأولي، ننصحك بشدة باسترداد أحدث رمز تسجيل معدَّل.

قد يتغيّر رمز التسجيل في الحالات التالية:

  • استعادة التطبيق على جهاز جديد
  • إلغاء تثبيت التطبيق وإعادة تثبيته
  • محو بيانات التطبيق

استرداد رمز التسجيل الحالي

عندما تحتاج إلى استرداد الرمز المميّز الحالي، استخدِم FirebaseMessaging.getInstance().getToken():

Kotlin

FirebaseMessaging.getInstance().token.addOnCompleteListener(OnCompleteListener { task ->
    if (!task.isSuccessful) {
        Log.w(TAG, "Fetching FCM registration token failed", task.exception)
        return@OnCompleteListener
    }

    // Get new FCM registration token
    val token = task.result

    // Log and toast
    val msg = getString(R.string.msg_token_fmt, token)
    Log.d(TAG, msg)
    Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show()
})

Java

FirebaseMessaging.getInstance().getToken()
    .addOnCompleteListener(new OnCompleteListener<String>() {
        @Override
        public void onComplete(@NonNull Task<String> task) {
          if (!task.isSuccessful()) {
            Log.w(TAG, "Fetching FCM registration token failed", task.getException());
            return;
          }

          // Get new FCM registration token
          String token = task.getResult();

          // Log and toast
          String msg = getString(R.string.msg_token_fmt, token);
          Log.d(TAG, msg);
          Toast.makeText(MainActivity.this, msg, Toast.LENGTH_SHORT).show();
        }
    });

تتبُّع إنشاء الرمز المميّز

يتم تفعيل معاودة الاتصال onNewToken كلما تم إنشاء رمز مميّز جديد.

Kotlin

/**
 * Called if the FCM registration token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the
 * FCM registration token is initially generated so this is where you would retrieve the token.
 */
override fun onNewToken(token: String) {
    Log.d(TAG, "Refreshed token: $token")

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token)
}
MyFirebaseMessagingService.kt

Java

/**
 * There are two scenarios when onNewToken is called:
 * 1) When a new token is generated on initial app startup
 * 2) Whenever an existing token is changed
 * Under #2, there are three scenarios when the existing token is changed:
 * A) App is restored to a new device
 * B) User uninstalls/reinstalls the app
 * C) User clears app data
 */
@Override
public void onNewToken(@NonNull String token) {
    Log.d(TAG, "Refreshed token: " + token);

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token);
}
MyFirebaseMessagingService.java

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

التحقّق من توفّر "خدمات Google Play"

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

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

منع الإعداد التلقائي

عند إنشاء رمز تسجيل FCM، تحمِّل المكتبة المعرّف وبيانات الإعداد إلى Firebase. إذا كنت تفضّل منع إنشاء الرمز المميّز تلقائيًا، عليك إيقاف جمع البيانات في "إحصاءات 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" />
AndroidManifest.xml

لإعادة تفعيل الإعداد التلقائي في "مراسلة Firebase السحابية"، استخدِم استدعاءً أثناء وقت التشغيل:

Kotlin

Firebase.messaging.isAutoInitEnabled = true
MainActivity.kt

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);
MainActivity.java

لإعادة تفعيل جمع البيانات في "إحصاءات Google"، استخدِم طريقة setAnalyticsCollectionEnabled() لفئة FirebaseAnalytics. على سبيل المثال:

setAnalyticsCollectionEnabled(true);

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

إرسال رسالة إشعار

للتأكّد من إعداد عميل Android بشكل صحيح، يمكنك إرسال رسالة إشعار اختبارية باستخدام التعليمات التالية:

  1. ثبِّت التطبيق وشغِّله على جهاز الاختبار.
  2. تأكَّد من أنّ التطبيق يعمل في الخلفية على الجهاز.
  3. في وحدة تحكّم Firebase، افتح صفحة المراسلة.
  4. إذا كانت هذه هي رسالتك الأولى، اختَر إنشاء حملتك الأولى، رسائل إشعارات Firebase، ثم إنشاء.
  5. بخلاف ذلك، في علامة التبويب الحملات ، اختَر حملة جديدة ، ثم الإشعارات.
  6. أدخِل نص الرسالة. جميع الحقول الأخرى اختيارية.
  7. اختَر إرسال رسالة اختبارية من اللوحة اليمنى.
  8. في الحقل الذي يحمل العنوان إضافة رمز تسجيل في "مراسلة Firebase السحابية"، أدخِل رمز التسجيل الذي حصلت عليه في قسم سابق من هذا الدليل.
  9. اختَر اختبار.

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

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

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

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