Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

اختيار المنصة:

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

تتطلّب عملاء FCM أجهزة تعمل بنظام التشغيل Android 6.0 أو إصدار أحدث ومثبَّت عليها تطبيق "متجر Google Play"، أو محاكي يعمل بنظام التشغيل Android 6.0 مع واجهات Google APIs. تجدر الإشارة إلى أنّه لا يمكنك نشر تطبيقات 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

(اختياري) بدءًا من الإصدار 8.0 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 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

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

يقدّم نظام التشغيل 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 من المستخدم.

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

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

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

اختياري: إزالة إذن `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" والإعداد التلقائي لخدمة 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" />AndroidManifest.xml

لإعادة تفعيل ميزة "الإعداد التلقائي" في FCM، عليك إجراء عملية استدعاء في وقت التشغيل:

Kotlin

Firebase.messaging.isAutoInitEnabled = trueMainActivity.kt

Java

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

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

setAnalyticsCollectionEnabled(true);

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

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

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

ثبِّت التطبيق وشغِّله على جهاز الاختبار.
تأكَّد من تشغيل التطبيق في الخلفية على الجهاز.
في وحدة تحكّم Firebase، انتقِل إلى عمليات DevOps ومعدّل الاهتمام بالتطبيق > المراسلة.
أنشئ حملة.
- إذا كانت هذه هي رسالتك الأولى:
  1. انقر على إنشاء حملتك الأولى.
  2. اختَر رسائل إشعارات Firebase، ثمّ اختَر إنشاء.
- إذا سبق لك إنشاء حملات:
  1. في علامة التبويب الحملات، انقر على حملة جديدة.
  2. انقر على الإشعارات.
أدخِل نص الرسالة، وجميع الحقول الأخرى اختيارية.
انقر على إرسال رسالة اختبار من اللوحة اليمنى.
في الحقل الذي يحمل التصنيف إضافة رمز مميّز للتسجيل في FCM، أدخِل رمز التسجيل الذي حصلت عليه في قسم سابق من هذا الدليل.
انقر على اختبار.

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

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

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

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

بدء استخدام "المراسلة عبر السحابة الإلكترونية من Firebase" في تطبيقات Android تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

Kotlin

Java

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

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

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

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

Kotlin

Java

مراقبة إنشاء الرموز المميزة

Kotlin

Java

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

منع بدء التشغيل التلقائي

Kotlin

Java

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

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

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

اختياري: إزالة إذن `POST_NOTIFICATIONS`