برای شروع کار با FCM ، سادهترین مورد استفاده را بسازید: ارسال یک پیام اعلان آزمایشی از سازنده Notifications به یک دستگاه توسعهدهنده زمانی که برنامه در پسزمینه دستگاه است. این صفحه تمام مراحل برای رسیدن به این هدف را از راهاندازی تا تأیید فهرست میکند - اگر یک برنامه کلاینت Android برای FCM راهاندازی کرده باشید، ممکن است مراحلی را که قبلاً انجام دادهاید پوشش دهد.
SDK را تنظیم کنید
اگر قبلاً سایر ویژگی های Firebase را برای برنامه خود فعال کرده باشید، این بخش وظایفی را که ممکن است انجام داده باشید را پوشش می دهد.
قبل از شروع
اندروید استودیو را به آخرین نسخه خود نصب یا به روز کنید.
مطمئن شوید که پروژه شما این الزامات را برآورده می کند (توجه داشته باشید که برخی از محصولات ممکن است الزامات سخت گیرانه تری داشته باشند):
- سطح 19 API (KitKat) یا بالاتر را هدف قرار می دهد
- از اندروید 4.4 یا بالاتر استفاده می کند
- از Jetpack (AndroidX) استفاده میکند که شامل برآورده کردن الزامات نسخه است:
-
com.android.tools.build:gradle
v7.3.0 یا جدیدتر -
compileSdkVersion
28 یا بالاتر
-
یک دستگاه فیزیکی راه اندازی کنید یا از یک شبیه ساز برای اجرای برنامه خود استفاده کنید.
توجه داشته باشید که Firebase SDK با وابستگی به خدمات Google Play به دستگاه یا شبیه ساز نیاز دارد که سرویس های Google Play را نصب کرده باشد.با استفاده از حساب Google خود وارد Firebase شوید .
اگر قبلاً پروژه Android ندارید و فقط میخواهید یک محصول Firebase را امتحان کنید، میتوانید یکی از نمونههای شروع سریع ما را دانلود کنید.
یک پروژه Firebase ایجاد کنید
قبل از اینکه بتوانید Firebase را به برنامه Android خود اضافه کنید، باید یک پروژه Firebase برای اتصال به برنامه Android خود ایجاد کنید. برای کسب اطلاعات بیشتر در مورد پروژه های Firebase، از Understand Firebase Projects دیدن کنید.
برنامه خود را با Firebase ثبت کنید
برای استفاده از Firebase در برنامه Android خود، باید برنامه خود را در پروژه Firebase خود ثبت کنید. ثبت برنامه شما اغلب "افزودن" برنامه شما به پروژه شما نامیده می شود.
به کنسول Firebase بروید.
در مرکز صفحه نمای کلی پروژه، روی نماد Android (
) یا افزودن برنامه کلیک کنید تا گردش کار راه اندازی راه اندازی شود.نام بسته برنامه خود را در قسمت نام بسته Android وارد کنید.
نام بسته به طور منحصر به فرد برنامه شما را در دستگاه و در فروشگاه Google Play شناسایی می کند.
نام بسته اغلب به عنوان شناسه برنامه شناخته می شود.
نام بسته برنامه خود را در ماژول خود (سطح برنامه) فایل Gradle، معمولا
app/build.gradle
(نام بسته نمونه:com.yourcompany.yourproject
) پیدا کنید.توجه داشته باشید که مقدار نام بسته به حروف کوچک و بزرگ حساس است و نمیتوان آن را برای این برنامه Android Firebase پس از ثبت نام در پروژه Firebase تغییر داد.
(اختیاری) اطلاعات دیگر برنامه را وارد کنید: نام مستعار برنامه و گواهی امضای اشکال زدایی SHA-1 .
نام مستعار برنامه : یک شناسه داخلی و راحت که فقط برای شما در کنسول Firebase قابل مشاهده است
گواهی امضای اشکال زدایی SHA-1 : یک هش SHA-1 توسط Firebase Authentication (هنگام استفاده از ورود به سیستم Google یا ورود به شماره تلفن ) و Firebase Dynamic Links لازم است.
روی ثبت برنامه کلیک کنید.
یک فایل پیکربندی Firebase اضافه کنید
فایل پیکربندی Android Firebase (
) را دانلود و سپس به برنامه خود اضافه کنید:google-services.json برای دریافت فایل پیکربندی Android Firebase خود، روی Download google-services.json کلیک کنید.
فایل پیکربندی خود را به پوشه اصلی ماژول (سطح برنامه) برنامه خود منتقل کنید.
فایل پیکربندی Firebase حاوی شناسههای منحصر به فرد، اما غیر مخفی برای پروژه شما است. برای کسب اطلاعات بیشتر در مورد این فایل پیکربندی، از Understand Firebase Projects دیدن کنید.
میتوانید فایل پیکربندی Firebase خود را دوباره در هر زمانی دانلود کنید.
مطمئن شوید که نام فایل پیکربندی با کاراکترهای اضافی مانند
(2)
اضافه نشده باشد.
برای دسترسی به مقادیر موجود در فایل پیکربندی
خود برای Firebase SDK، به افزونه Gradle خدمات Google (google-services.json google-services
) نیاز دارید.در فایل Gradle سطح ریشه (سطح پروژه) خود (
<project>/build.gradle.kts
یا<project>/build.gradle
)، افزونه خدمات Google را به عنوان یک وابستگی اضافه کنید: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.2" 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.2' apply false }
در فایل Gradle ماژول (سطح برنامه) خود (معمولا
<project>/<app-module>/build.gradle.kts
یا<project>/<app-module>/build.gradle
)، افزونه خدمات Google را اضافه کنید: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' // ... }
SDK های Firebase را به برنامه خود اضافه کنید
در فایل Gradle ماژول (سطح برنامه) خود (معمولا
<project>/<app-module>/build.gradle.kts
یا<project>/<app-module>/build.gradle
)، وابستگی را برای Firebase Cloud Messaging اضافه کنید. کتابخانه 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:33.3.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 Android استفاده میکند.
به دنبال یک ماژول کتابخانه خاص کاتلین هستید؟ از اکتبر 2023 ( Firebase BoM 32.5.0) ، توسعه دهندگان Kotlin و Java می توانند به ماژول کتابخانه اصلی وابسته باشند (برای جزئیات، به سؤالات متداول در مورد این ابتکار مراجعه کنید).(جایگزین) وابستگی های کتابخانه 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:24.0.1") implementation("com.google.firebase:firebase-analytics:22.1.0") }
پروژه اندروید خود را با فایل های Gradle همگام سازی کنید.
ساختهای Gradle که از افزونه Android Gradle (AGP) نسخه 4.2 یا نسخههای قبلی استفاده میکنند، باید پشتیبانی از جاوا 8 را فعال کنند. در غیر این صورت، این پروژههای اندرویدی هنگام اضافه کردن Firebase SDK با شکست ساخت مواجه میشوند.
برای رفع این خرابی ساخت، می توانید یکی از دو گزینه را دنبال کنید:
-
compileOptions
فهرست شده را از پیام خطا به فایلbuild.gradle.kts
یاbuild.gradle
سطح برنامه خود اضافه کنید. -
minSdk
پروژه اندروید خود را به 26 یا بالاتر افزایش دهید.
در این سؤالات متداول درباره این شکست ساخت بیشتر بیاموزید.
-
به رمز ثبت نام دسترسی پیدا کنید
برای ارسال پیام به یک دستگاه خاص، باید رمز ثبت نام آن دستگاه را بدانید. از آنجایی که برای تکمیل این آموزش باید توکن را در قسمتی در کنسول Notifications وارد کنید، پس از بازیابی آن حتماً آن را کپی کنید یا به طور ایمن ذخیره کنید.
در راه اندازی اولیه برنامه شما، 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); }
پس از دریافت رمز، می توانید آن را به سرور برنامه خود ارسال کرده و با استفاده از روش دلخواه خود، آن را ذخیره کنید.
یک پیام اعلان آزمایشی ارسال کنید
برنامه را روی دستگاه مورد نظر نصب و اجرا کنید. در دستگاههای اپل، باید درخواست مجوز برای دریافت اعلانهای از راه دور را بپذیرید.
مطمئن شوید که برنامه در پسزمینه دستگاه است.
در کنسول Firebase ، صفحه پیامرسانی را باز کنید.
اگر این اولین پیام شماست، ایجاد اولین کمپین خود را انتخاب کنید.
- پیامهای اعلان Firebase را انتخاب کنید و ایجاد را انتخاب کنید.
در غیر این صورت، در تب Campaigns ، کمپین جدید و سپس Notifications را انتخاب کنید.
متن پیام را وارد کنید تمام فیلدهای دیگر اختیاری هستند.
از قسمت سمت راست گزینه Send test message را انتخاب کنید.
در فیلد با عنوان افزودن نشانه ثبت FCM ، نشانه ثبت نامی را که در بخش قبلی این راهنما به دست آورده اید، وارد کنید.
تست را انتخاب کنید.
پس از انتخاب تست ، دستگاه مشتری مورد نظر (با برنامه در پسزمینه) باید اعلان را دریافت کند.
برای اطلاعات بیشتر در مورد تحویل پیام به برنامه خود، به داشبورد گزارش FCM مراجعه کنید، که تعداد پیامهای ارسال شده و باز شده در دستگاههای Apple و Android را به همراه دادههای «impressions» (اعلانهایی که کاربران مشاهده میکنند) را برای برنامههای Android ثبت میکند.
مراحل بعدی
ارسال پیام به برنامه های پیش زمینه
هنگامی که با موفقیت پیامهای اعلان ارسال کردید، در حالی که برنامه شما در پسزمینه است، برای شروع ارسال به برنامههای پیشزمینه ، به دریافت پیامها در برنامه Android مراجعه کنید.
فراتر از پیام های اطلاع رسانی بروید
برای فراتر رفتن از پیامهای اعلان و افزودن سایر رفتارهای پیشرفتهتر به برنامه خود، ببینید: