با Firebase Cloud Messaging شروع کنید


این راهنمای سریع نحوه راه‌اندازی Firebase Cloud Messaging را در برنامه‌های موبایل و کلاینت وب شما شرح می‌دهد تا بتوانید پیام‌ها را به طور قابل اعتمادی ارسال کنید. برای محیط‌های سرور، به بخش Your server environment and FCM مراجعه کنید.

شروع کار با Firebase Cloud Messaging و اندروید

کلاینت‌های FCM به دستگاه‌هایی با اندروید ۵.۰ یا بالاتر نیاز دارند که برنامه Google Play Store نیز روی آنها نصب شده باشد، یا به یک شبیه‌ساز که اندروید ۵.۰ را با APIهای گوگل اجرا می‌کند. توجه داشته باشید که شما محدود به استقرار برنامه‌های اندروید خود از طریق Google Play Store نیستید.

راه‌اندازی SDK

اگر هنوز Firebase را به پروژه اندروید خود اضافه نکرده‌اید، آن را اضافه کنید.

برای تجربه بهینه با 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
  • (اختیاری) درون کامپوننت برنامه، عناصر فراداده برای تنظیم آیکون و رنگ پیش‌فرض اعلان. اندروید از این مقادیر هر زمان که پیام‌های دریافتی به طور صریح آیکون یا رنگ را تنظیم نمی‌کنند، استفاده می‌کند. 
    • <!-- 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
  • (اختیاری) از اندروید ۸.۰ (سطح API ۲۶) و بالاتر، کانال‌های اعلان پشتیبانی و توصیه می‌شوند. 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

درخواست مجوز اعلان زمان اجرا در اندروید ۱۳+

اندروید ۱۳ یک مجوز جدید در زمان اجرا برای نمایش اعلان‌ها معرفی می‌کند. این مجوز روی تمام برنامه‌هایی که روی اندروید ۱۳ یا بالاتر اجرا می‌شوند و از اعلان‌های FCM استفاده می‌کنند، تأثیر می‌گذارد.

به طور پیش‌فرض، FCM SDK (نسخه ۲۳.۰.۶ یا بالاتر) شامل مجوز 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

به طور کلی، شما باید یک رابط کاربری (UI) را به کاربر نمایش دهید که در صورت اعطای مجوز به برنامه برای ارسال اعلان‌ها، ویژگی‌هایی را که فعال می‌شوند، برای او توضیح دهد. این رابط کاربری باید گزینه‌هایی را برای موافقت یا رد، مانند دکمه‌های OK و No thanks ، در اختیار کاربر قرار دهد. اگر کاربر OK را انتخاب کرد، مستقیماً درخواست مجوز کنید. اگر کاربر No thanks را انتخاب کرد، به کاربر اجازه دهید بدون اعلان‌ها ادامه دهد.

برای آشنایی با بهترین شیوه‌های استفاده از مجوز POST_NOTIFICATIONS در برنامه‌تان، به بخش «مجوز زمان اجرای اعلان‌ها» مراجعه کنید.

مجوزهای اعلان برای برنامه‌هایی که اندروید ۱۲L (سطح API ۳۲) یا پایین‌تر را هدف قرار می‌دهند

اندروید به طور خودکار در اولین باری که برنامه شما یک کانال اعلان ایجاد می‌کند، تا زمانی که برنامه در پیش‌زمینه باشد، از کاربر اجازه می‌گیرد. با این حال، نکات مهمی در مورد زمان ایجاد کانال و درخواست‌های مجوز وجود دارد:

  • اگر برنامه شما اولین کانال اعلان خود را هنگام اجرا در پس‌زمینه ایجاد کند، کاری که FCM SDK هنگام دریافت اعلان FCM انجام می‌دهد، اندروید اجازه نمایش اعلان را نمی‌دهد و تا دفعه بعد که برنامه شما باز شود، از کاربر درخواست مجوز اعلان نمی‌کند. این بدان معناست که هرگونه اعلانی که قبل از باز شدن برنامه شما و پذیرش مجوز توسط کاربر دریافت شده باشد، از بین خواهد رفت.
  • اکیداً توصیه می‌کنیم برنامه خود را برای اندروید ۱۳+ به‌روزرسانی کنید تا از APIهای پلتفرم برای درخواست مجوز استفاده کنید. اگر این امکان وجود ندارد، برنامه شما باید قبل از ارسال هرگونه اعلان به برنامه، کانال‌های اعلان ایجاد کند تا کادر محاوره‌ای مجوز اعلان فعال شود و مطمئن شوید که هیچ اعلانی از دست نمی‌رود. برای اطلاعات بیشتر به بهترین شیوه‌های مجوز اعلان مراجعه کنید.

اختیاری: حذف مجوز 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 

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

پس از دریافت توکن، می‌توانید آن را به سرور برنامه خود ارسال کرده و با استفاده از روش دلخواه خود ذخیره کنید.

سرویس‌های گوگل پلی را بررسی کنید

برنامه‌هایی که به SDK سرویس‌های Play متکی هستند، باید همیشه قبل از دسترسی به ویژگی‌های سرویس‌های Google Play، دستگاه را از نظر سازگاری با APK سرویس‌های Google Play بررسی کنند. برای کسب اطلاعات بیشتر، به بخش راه‌اندازی سرویس‌های Google Play مراجعه کنید. توصیه می‌شود این کار را در دو مکان انجام دهید: در متد onCreate() در فعالیت اصلی و در متد onResume() آن. بررسی onCreate() اطمینان حاصل می‌کند که برنامه بدون بررسی موفقیت‌آمیز قابل استفاده نیست. بررسی onResume() اطمینان حاصل می‌کند که اگر کاربر از طریق روش‌های دیگری، مانند دکمه برگشت، به برنامه در حال اجرا بازگردد، بررسی همچنان انجام می‌شود.

اگر دستگاه نسخه سازگار با سرویس‌های گوگل پلی را نداشته باشد، برنامه شما می‌تواند تابع GoogleApiAvailability.makeGooglePlayServicesAvailable() را فراخوانی کند تا به کاربران اجازه دهد سرویس‌های گوگل پلی را از فروشگاه پلی دانلود کنند.

جلوگیری از مقداردهی اولیه خودکار

وقتی یک توکن ثبت 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 

Firebase.messaging.isAutoInitEnabled = true
MainActivity.kt

Java 

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

برای فعال‌سازی مجدد مجموعه‌ی Analytics، متد setAnalyticsCollectionEnabled() از کلاس FirebaseAnalytics را فراخوانی کنید. برای مثال: 

setAnalyticsCollectionEnabled(true);

این مقادیر پس از تنظیم، در طول راه‌اندازی مجدد برنامه باقی می‌مانند.

ارسال پیام اطلاع رسانی

برای اطمینان از اینکه کلاینت اندروید شما به درستی تنظیم شده است، می‌توانید با استفاده از دستورالعمل‌های زیر یک پیام اعلان آزمایشی ارسال کنید:

  1. برنامه را روی دستگاه هدف نصب و اجرا کنید.
  2. مطمئن شوید که برنامه در پس‌زمینه دستگاه فعال است.
  3. در کنسول Firebase ، صفحه پیام‌رسانی (Messaging) را باز کنید.
  4. اگر این اولین پیام شماست، گزینه Create your first campaign ، Firebase Notification messages و سپس Create را انتخاب کنید.
  5. در غیر این صورت، در برگه کمپین‌ها ، کمپین جدید و سپس اعلان‌ها را انتخاب کنید.
  6. متن پیام را وارد کنید. سایر فیلدها اختیاری هستند.
  7. از پنل سمت راست، گزینه ارسال پیام آزمایشی را انتخاب کنید.
  8. در فیلدی با عنوان « افزودن یک توکن ثبت نام FCM» ، توکن ثبت نامی را که در بخش قبلی این راهنما دریافت کرده‌اید، وارد کنید.
  9. آزمون را انتخاب کنید.

دستگاه کلاینت مورد نظر، با برنامه در پس‌زمینه، باید اعلان را دریافت کند.

برای اطلاعات بیشتر در مورد ارسال پیام به برنامه خود، به داشبورد گزارش FCM مراجعه کنید، که تعداد پیام‌های ارسالی و باز شده در دستگاه‌های اپل و اندروید را به همراه داده‌های مربوط به نمایش‌ها (اعلان‌های مشاهده شده توسط کاربران) برای برنامه‌های اندروید ثبت می‌کند.

مراحل بعدی

پس از اتمام مراحل راه‌اندازی، در اینجا چند گزینه برای ادامه کار با FCM برای اندروید ارائه شده است: