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

اختيار نظام أساسي: iOS+ Android Web Flutter Unity C++


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

تتطلّب أجهزة عملاء FCM نظام التشغيل Android 7.0 أو إصدارًا أحدث، وأن يكون تطبيق "متجر Google Play" مثبّتًا عليها، أو محاكيًا يعمل بنظام التشغيل Android 7.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>
  • (اختياري) ضمن مكوّن التطبيق، عناصر البيانات الوصفية لضبط رمز إشعار ولون تلقائيَين يستخدم 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 (مستوى واجهة برمجة التطبيقات 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 الإشعارات.

تتضمّن حزمة تطوير البرامج (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)
        }
    }
}

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 (المستوى 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"/>

الوصول إلى رقم تعريف تثبيت Firebase

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

تفعيل التسجيل من خلال رقم تعريف تثبيت Firebase

لتفعيل تسجيل مثيل تطبيقك في FCM باستخدام رقم تعريف تثبيت Firebase، أضِف علامة البيانات الوصفية التالية إلى ملف AndroidManifest.xml 
<meta-data
    android:name="firebase_messaging_installation_id_enabled"
    android:value="true" />

تنفيذ دالة الاستدعاء onRegistered()

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

Kotlin

  /**
   * There are three scenarios when `onRegistered` is called:
   * 1) Every time a manual `register()` call finishes successfully
   * 2) Whenever the FID is changed and the app is re-registered with FCM via the new FID.
   * 3) Automatically on app startup or routine sync when auto-initialization is enabled.
   * Under #2, there are three scenarios when the existing FID is changed:
   * A) App is restored to a new device
   * B) User uninstalls/reinstalls the app
   * C) User clears app data
   */
  override fun onRegistered(installationId: String) {
      Log.d(TAG, "Registered installation ID: $installationId")

      // Send the Firebase Installation ID to your app server.
      sendRegistrationToServer(installationId)
  }

Java

  /**
   * There are three scenarios when `onRegistered` is called:
   * 1) Every time a manual `register()` call finishes successfully
   * 2) Whenever the FID is changed and the app is re-registered with FCM via the new FID
   * 3) Automatically on app startup or routine sync when auto-initialization is enabled.
   * Under #2, there are three scenarios when the existing FID is changed:
   * A) App is restored to a new device
   * B) User uninstalls/reinstalls the app
   * C) User clears app data
   */
  @Override
  public void onRegistered(@NonNull String installationId) {
      Log.d(TAG, "Registered installation ID: " + installationId);

      // Send the Firebase Installation ID to your app server.
      sendRegistrationToServer(installationId);
  }

التسجيل يدويًا عند إيقاف ميزة "الإعداد التلقائي"

إذا كان عليك إيقاف ميزة "الإعداد التلقائي"، لن تتم مزامنة FCM حزمة تطوير البرامج (SDK) تلقائيًا أو تفعيل دالة الاستدعاء onRegistered() عند بدء التشغيل. ننصحك بشدة بإعادة تفعيل ميزة "الإعداد التلقائي" بعد منح إذن إرسال الإشعارات. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعادة تفعيل ميزة "الإعداد التلقائي".

إذا كان يجب إيقاف ميزة "الإعداد التلقائي"، استدعِ FirebaseMessaging.getInstance().register() عند بدء تشغيل التطبيق لتفعيل التسجيل وتسليم رقم تعريف تثبيت Firebase من خلال onRegistered() دالة الاستدعاء. يمكنك تنفيذ هذا الاستدعاء ضمن onCreate() طريقة في Activity الرئيسية.

Kotlin

  // Trigger manual registration if auto-initialization is turned off.
  // Consider calling this every time the app starts to guarantee sync status.
  FirebaseMessaging.getInstance().register()
      .addOnCompleteListener(this) { task ->
        if (!task.isSuccessful()) {
          // Registration failed. Consider retrying the registration with exponential backoff.
          Log.w(TAG, "Failed to register with Firebase Cloud Messaging", task.exception)
        }
        // Success! The Firebase Installation ID can be used to target messages to this app
        // instance and will be delivered asynchronously to your `onRegistered()` callback.
      }

Java

  // Trigger manual registration if auto-initialization is turned off.
  // Consider calling this every time the app starts to guarantee sync status.
  FirebaseMessaging.getInstance().register()
      .addOnCompleteListener(task -> {
        if (!task.isSuccessful()) {
          // Registration failed. Consider retrying the registration with exponential backoff.
          Log.w(TAG, "Failed to register with Firebase Cloud Messaging", task.exception)
        }
        // Success! The Firebase Installation ID can be used to target messages to this app
        // instance and will be delivered asynchronously to your `onRegistered()` callback.
      });

الوصول إلى رمز التسجيل FCM (تم إيقافه نهائيًا)

عند بدء تشغيل تطبيقك لأول مرة، تُنشئ حزمة تطوير البرامج 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)
}

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"

يجب أن تتحقّق التطبيقات التي تعتمد على حزمة تطوير البرامج (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" />

إعادة تفعيل ميزة "الإعداد التلقائي"

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

Kotlin

Firebase.messaging.isAutoInitEnabled = true

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

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

setAnalyticsCollectionEnabled(true);

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

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

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

  1. ثبِّت التطبيق وشغِّله على جهاز الاختبار.

  2. تأكَّد من أنّ التطبيق يعمل في الخلفية على الجهاز.

  3. في وحدة تحكّم Firebase، انتقِل إلى عمليات DevOps والتفاعل > المراسلة

  4. أنشئ حملة.

    • إذا كانت هذه هي رسالتك الأولى:

      1. انقر على إنشاء أول حملة لك.

      2. انقر على إشعارات Firebase ، ثم على إنشاء.

    • إذا سبق لك إنشاء حملات:

      1. في علامة التبويب الحملات ، انقر على حملة جديدة.

      2. انقر على الإشعارات.

  5. أدخِل نص الرسالة. جميع الحقول الأخرى اختيارية.

  6. انقر على إرسال رسالة اختبارية من اللوحة اليمنى.

  7. في الحقل الذي يحمل العنوان إضافة رمز تسجيل في خدمة "مراسلة Firebase السحابية"، أدخِل رمز التسجيل الذي حصلت عليه في قسم سابق من هذا الدليل.

  8. انقر على اختبار.

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

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

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

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