قم بإعداد تطبيق عميل Firebase Cloud Messaging على Android

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

قم بإعداد SDK

يغطي هذا القسم المهام التي قد تكون أكملتها إذا قمت بالفعل بتمكين ميزات Firebase الأخرى لتطبيقك. إذا لم تكن قد قمت بذلك بالفعل، فأضف Firebase إلى مشروع Android الخاص بك

تحرير بيان التطبيق الخاص بك

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

  • خدمة تمتد FirebaseMessagingService . يعد هذا مطلوبًا إذا كنت تريد القيام بأي معالجة للرسائل بخلاف تلقي الإشعارات على التطبيقات في الخلفية. لتلقي الإشعارات في التطبيقات المقدمة، ولتلقي حمولة البيانات، ولإرسال رسائل المنبع، وما إلى ذلك، يجب عليك توسيع هذه الخدمة.
  • <service
        android:name=".java.MyFirebaseMessagingService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
  • (اختياري) ضمن مكون التطبيق، عناصر البيانات التعريفية لتعيين رمز ولون إشعار افتراضي. يستخدم 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" />
  • (اختياري) بدءًا من Android 8.0 (مستوى API 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" />

طلب إذن إشعار وقت التشغيل على Android 13+

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

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

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

Kotlin+KTX

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

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);
        }
    }
}

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

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

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

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

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

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

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

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

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

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

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

قد يتغير رمز التسجيل عندما:

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

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

عندما تحتاج إلى استرداد الرمز المميز الحالي، اتصل بـ FirebaseMessaging.getInstance().getToken() :

Kotlin+KTX

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+KTX

/**
 * 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)
}

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);
}

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

تحقق من خدمات Google Play

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

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

منع التهيئة التلقائية

عند إنشاء رمز تسجيل FCM، تقوم المكتبة بتحميل المعرف وبيانات التكوين إلى Firebase. إذا كنت تفضل منع الإنشاء التلقائي للرمز المميز، فقم بتعطيل مجموعة Analytics والتهيئة التلقائية لـ 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، قم بإجراء مكالمة وقت التشغيل:

Kotlin+KTX

Firebase.messaging.isAutoInitEnabled = true

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

لإعادة تمكين مجموعة Analytics، اتصل بالطريقة setAnalyticsCollectionEnabled() ‎ لفئة FirebaseAnalytics . على سبيل المثال:

setAnalyticsCollectionEnabled(true);

تستمر هذه القيم عبر عمليات إعادة تشغيل التطبيق بمجرد تعيينها.

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

بعد إعداد تطبيق العميل، تصبح جاهزًا لبدء إرسال الرسائل النهائية باستخدام مؤلف الإشعارات . تم توضيح هذه الوظيفة في نموذج التشغيل السريع ، والذي يمكنك تنزيله وتشغيله ومراجعته.

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

ضع في اعتبارك أنه للاستفادة من هذه الميزات، ستحتاج إلى تنفيذ الخادم وبروتوكولات الخادم (HTTP أو XMPP)، أو تنفيذ Admin SDK .