تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

تتطلب عملاء FCM أجهزة تعمل بنظام Android 4.4 أو إصدار أحدث مثبت عليها أيضًا تطبيق متجر Google Play ، أو محاكي يعمل بنظام 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>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 (مستوى 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" />AndroidManifest.xml

طلب إذن إعلام وقت التشغيل على 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)
        }
    }
}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 (مستوى 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)
}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

يجب أن تتحقق التطبيقات التي تعتمد على 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" />AndroidManifest.xml

لإعادة تمكين التهيئة التلقائية لـ FCM ، قم بإجراء مكالمة وقت التشغيل:

Kotlin+KTX

Firebase.messaging.isAutoInitEnabled = trueMainActivity.kt

Java

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

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

setAnalyticsCollectionEnabled(true);

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

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

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

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

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

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

قم بإعداد SDK

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

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

Kotlin+KTX

Java

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

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

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

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

Kotlin+KTX

Java

مراقبة توليد الرمز المميز

Kotlin+KTX

Java

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

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

Kotlin+KTX

Java

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

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