یک پیام آزمایشی به یک برنامه پس‌زمینه ارسال کنید

برای شروع کار با FCM ، ساده‌ترین مورد استفاده را بسازید: ارسال یک پیام اعلان آزمایشی از کامپوزر Notifications به یک دستگاه در حال توسعه، زمانی که برنامه در پس‌زمینه دستگاه است. این صفحه تمام مراحل دستیابی به این هدف، از راه‌اندازی تا تأیید را فهرست می‌کند - اگر یک برنامه کلاینت اندروید برای FCM راه‌اندازی کرده‌اید، ممکن است مراحلی را که قبلاً انجام داده‌اید، پوشش دهد.

SDK را تنظیم کنید

این بخش شامل وظایفی است که اگر قبلاً سایر ویژگی‌های Firebase را برای برنامه خود فعال کرده‌اید، ممکن است انجام داده باشید.

قبل از اینکه شروع کنی

• اندروید استودیو را به آخرین نسخه نصب یا به‌روزرسانی کنید.

• مطمئن شوید که پروژه شما این الزامات را برآورده می‌کند (توجه داشته باشید که برخی از محصولات ممکن است الزامات سختگیرانه‌تری داشته باشند):

  • هدف API سطح ۲۱ (لالی‌پاپ) یا بالاتر
  • از اندروید ۵.۰ یا بالاتر استفاده می‌کند
  • از Jetpack (AndroidX) استفاده می‌کند که شامل برآورده کردن این الزامات نسخه می‌شود:
    • com.android.tools.build:gradle نسخه ۷.۳.۰ یا بالاتر
    • compileSdkVersion ۲۸ یا بالاتر

• یک دستگاه فیزیکی راه‌اندازی کنید یا از یک شبیه‌ساز برای اجرای برنامه خود استفاده کنید.
  توجه داشته باشید که SDK های فایربیس که به سرویس‌های گوگل پلی وابسته هستند، نیاز دارند که دستگاه یا شبیه‌ساز، سرویس‌های گوگل پلی را نصب کرده باشد.

• با استفاده از حساب گوگل خود وارد فایربیس شوید .

اگر از قبل پروژه اندروید ندارید و فقط می‌خواهید یک محصول Firebase را امتحان کنید، می‌توانید یکی از نمونه‌های شروع سریع ما را دانلود کنید.

ایجاد یک پروژه فایربیس

قبل از اینکه بتوانید Firebase را به برنامه اندروید خود اضافه کنید، باید یک پروژه Firebase ایجاد کنید تا به برنامه اندروید شما متصل شود. برای کسب اطلاعات بیشتر در مورد پروژه‌های Firebase، به بخش «درک پروژه‌های Firebase» مراجعه کنید.

برنامه خود را با Firebase ثبت کنید

برای استفاده از فایربیس در برنامه اندروید خود، باید برنامه خود را در پروژه فایربیس خود ثبت کنید. ثبت برنامه اغلب "افزودن" برنامه به پروژه شما نامیده می‌شود.

1. به کنسول Firebase بروید.

2. در مرکز صفحه نمای کلی پروژه، روی آیکون اندروید ( plat_android ) یا افزودن برنامه کلیک کنید تا گردش کار راه‌اندازی شود.

3. نام بسته برنامه خود را در فیلد نام بسته اندروید وارد کنید.

   نام بسته چیست و از کجا می‌توان آن را پیدا کرد؟

   • نام بسته، برنامه شما را به طور منحصر به فرد در دستگاه و فروشگاه گوگل پلی مشخص می‌کند.

   • نام بسته اغلب به عنوان شناسه برنامه (Application ID) شناخته می‌شود.

   • نام بسته برنامه خود را در فایل Gradle ماژول (سطح برنامه) خود، که معمولاً app/build.gradle است، پیدا کنید (به عنوان مثال نام بسته: com.yourcompany.yourproject ).

   • توجه داشته باشید که مقدار نام بسته به حروف بزرگ و کوچک حساس است و پس از ثبت برنامه اندروید Firebase در پروژه Firebase شما، نمی‌توان آن را برای این برنامه تغییر داد.

4. (اختیاری) یک نام مستعار برنامه وارد کنید، که یک شناسه داخلی و راحت است که فقط در کنسول Firebase برای شما قابل مشاهده است.

5. روی ثبت برنامه کلیک کنید.

یک فایل پیکربندی Firebase اضافه کنید

1. فایل پیکربندی فایربیس برنامه خود ( google-services.json ) را دانلود و سپس به کدبیس خود اضافه کنید:

   1. برای دریافت فایل پیکربندی Firebase برنامه خود، روی «دانلود google-services.json» کلیک کنید.

   2. فایل پیکربندی خود را به دایرکتوری ریشه ماژول (سطح برنامه) برنامه خود منتقل کنید.

   چه چیزهایی در مورد این فایل پیکربندی باید بدانید؟

   • فایل پیکربندی Firebase حاوی شناسه‌های منحصر به فرد اما غیر محرمانه برای پروژه و برنامه شما است. برای کسب اطلاعات بیشتر در مورد این فایل پیکربندی، به بخش «درک پروژه‌های Firebase» مراجعه کنید.

   • شما می‌توانید فایل پیکربندی Firebase خود را در هر زمانی دوباره دانلود کنید.

   • مطمئن شوید که نام فایل پیکربندی با کاراکترهای اضافی مانند (2) ضمیمه نشده باشد.

2. برای اینکه مقادیر موجود در فایل پیکربندی google-services.json شما برای SDK های Firebase قابل دسترسی باشند، به افزونه Gradle مربوط به سرویس‌های گوگل ( google-services ) نیاز دارید.

   1. در فایل Gradle سطح ریشه (سطح پروژه) خود ( <project>/build.gradle.kts یا <project>/build.gradle )، افزونه سرویس‌های گوگل را به عنوان یک وابستگی اضافه کنید:

      Kotlin

      plugins {
        id("com.android.application") version "7.3.0" apply false
        // ...
      
        // Add the dependency for the Google services Gradle plugin
        id("com.google.gms.google-services") version "4.4.4" apply false
      }

      Groovy

      plugins {
        id 'com.android.application' version '7.3.0' apply false
        // ...
      
        // Add the dependency for the Google services Gradle plugin
        id 'com.google.gms.google-services' version '4.4.4' apply false
      }

   2. در فایل Gradle ماژول (سطح برنامه) خود (معمولاً <project>/<app-module>/build.gradle.kts یا <project>/<app-module>/build.gradle )، افزونه سرویس‌های گوگل را اضافه کنید:

      Kotlin

      plugins {
        id("com.android.application")
      
        // Add the Google services Gradle plugin
        id("com.google.gms.google-services")
        // ...
      }

      Groovy

      plugins {
        id 'com.android.application'
      
        // Add the Google services Gradle plugin
        id 'com.google.gms.google-services'
        // ...
      }

اضافه کردن کیت‌های توسعه نرم‌افزار فایربیس به برنامه‌تان

1. در فایل Gradle ماژول (سطح برنامه) خود (معمولاً <project>/<app-module>/build.gradle.kts یا <project>/<app-module>/build.gradle )، وابستگی مربوط به کتابخانه Firebase Cloud Messaging برای اندروید را اضافه کنید. توصیه می‌کنیم از Firebase Android BoM برای کنترل نسخه‌بندی کتابخانه استفاده کنید.

   برای یک تجربه بهینه با Firebase Cloud Messaging ، توصیه می‌کنیم Google Analytics در پروژه Firebase خود فعال کنید و Firebase SDK را برای Google Analytics به برنامه خود اضافه کنید.

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:34.4.0"))
   
       // Add the dependencies for the Firebase Cloud Messaging and Analytics libraries
       // When using the BoM, you don't specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-messaging")
       implementation("com.google.firebase:firebase-analytics")
   }

   با استفاده از Firebase Android BoM ، برنامه شما همیشه از نسخه‌های سازگار کتابخانه‌های اندروید Firebase استفاده خواهد کرد.

   (جایگزین) اضافه کردن وابستگی‌های کتابخانه Firebase بدون استفاده از BoM

   اگر تصمیم به استفاده از Firebase BoM ندارید، باید هر نسخه از کتابخانه Firebase را در خط وابستگی آن مشخص کنید.

   توجه داشته باشید که اگر از چندین کتابخانه Firebase در برنامه خود استفاده می‌کنید، اکیداً توصیه می‌کنیم از BoM برای مدیریت نسخه‌های کتابخانه استفاده کنید، که تضمین می‌کند همه نسخه‌ها سازگار هستند.

   dependencies {
       // Add the dependencies for the Firebase Cloud Messaging and Analytics libraries
       // When NOT using the BoM, you must specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-messaging:25.0.1")
       implementation("com.google.firebase:firebase-analytics:23.0.0")
   }

2. پروژه اندروید خود را با فایل‌های Gradle همگام‌سازی کنید.

   آیا در مورد پشتیبانی از invoke-custom و فعال کردن desugaring با خطای ساخت مواجه می‌شوید؟ در اینجا نحوه رفع آن آمده است.

   نسخه‌های Gradle که از افزونه Android Gradle (AGP) نسخه ۴.۲ یا قدیمی‌تر استفاده می‌کنند، باید پشتیبانی از Java 8 را فعال کنند. در غیر این صورت، این پروژه‌های اندروید هنگام اضافه کردن Firebase SDK با خطای build مواجه می‌شوند.

   برای رفع این مشکل در ساخت و ساز، می‌توانید یکی از دو گزینه زیر را دنبال کنید:

   • compileOptions ذکر شده از پیام خطا را به فایل build.gradle.kts یا build.gradle در سطح برنامه خود اضافه کنید.
   • مقدار minSdk برای پروژه اندروید خود به ۲۶ یا بالاتر افزایش دهید.

   در این سوالات متداول درباره این شکست ساخت بیشتر بدانید.

دسترسی به توکن ثبت نام

برای ارسال پیام به یک دستگاه خاص، باید توکن ثبت آن دستگاه را بدانید. از آنجا که برای تکمیل این آموزش باید توکن را در فیلدی در کنسول اعلان‌ها وارد کنید، حتماً پس از بازیابی، توکن را کپی کرده یا آن را در جای امنی ذخیره کنید.

در هنگام راه‌اندازی اولیه برنامه، FCM SDK یک توکن ثبت‌نام برای نمونه برنامه کلاینت ایجاد می‌کند. اگر می‌خواهید دستگاه‌های منفرد را هدف قرار دهید یا گروه‌های دستگاه ایجاد کنید، باید با گسترش FirebaseMessagingService و لغو onNewToken به این توکن دسترسی پیدا کنید. از آنجا که توکن می‌تواند پس از راه‌اندازی اولیه تغییر کند، اکیداً توصیه می‌شود که آخرین توکن ثبت‌نام به‌روز شده را بازیابی کنید.

توکن ثبت نام ممکن است در موارد زیر تغییر کند:

• برنامه روی دستگاه جدید بازیابی شده است
• کاربر برنامه را حذف/نصب مجدد می‌کند
• کاربر داده‌های برنامه را پاک می‌کند.

بازیابی توکن ثبت نام فعلی

وقتی نیاز به بازیابی توکن فعلی دارید، FirebaseMessaging.getInstance().getToken() را فراخوانی کنید:

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

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 هر زمان که یک توکن جدید تولید شود، اجرا می‌شود.

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

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

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

ارسال پیام اطلاع رسانی آزمایشی

1. برنامه را روی دستگاه هدف نصب و اجرا کنید. در دستگاه‌های اپل، باید درخواست اجازه دریافت اعلان‌های از راه دور را بپذیرید.

2. مطمئن شوید که برنامه در پس‌زمینه دستگاه فعال است.

3. در کنسول Firebase ، صفحه پیام‌رسانی (Messaging) را باز کنید.

4. اگر این اولین پیام شماست، گزینه «ایجاد اولین کمپین» را انتخاب کنید.

   1. پیام‌های اعلان فایربیس و سپس ایجاد را انتخاب کنید.

5. در غیر این صورت، در برگه کمپین‌ها ، کمپین جدید و سپس اعلان‌ها را انتخاب کنید.

6. متن پیام را وارد کنید. سایر فیلدها اختیاری هستند.

7. از پنل سمت راست، گزینه ارسال پیام آزمایشی را انتخاب کنید.

8. در فیلدی با عنوان « افزودن یک توکن ثبت نام FCM» ، توکن ثبت نامی را که در بخش قبلی این راهنما دریافت کرده‌اید، وارد کنید.

9. آزمون را انتخاب کنید.

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

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

مراحل بعدی

ارسال پیام به برنامه‌های پیش‌فرض

وقتی که با موفقیت پیام‌های اعلان را در حالی که برنامه شما در پس‌زمینه است ارسال کردید، برای شروع ارسال به برنامه‌های پیش‌فرض، به بخش دریافت پیام‌ها در یک برنامه اندروید مراجعه کنید.

فراتر از پیام‌های اعلان بروید

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

• دریافت پیام در یک برنامه اندروید
• ارسال پیام به چندین دستگاه