این مراحل را برای راه اندازی یک کلاینت FCM در Flutter دنبال کنید.
تنظیمات و الزامات پلتفرم خاص
برخی از مراحل مورد نیاز بستگی به پلتفرمی دارد که شما هدف آن قرار می دهید.
iOS+
قابلیت های برنامه را در Xcode فعال کنید
قبل از اینکه برنامه شما بتواند پیامها را دریافت کند، باید اعلانهای فشار و حالتهای پسزمینه را در پروژه Xcode خود فعال کنید.
- فضای کاری پروژه Xcode خود را باز کنید (
ios/Runner.xcworkspace
). - اعلانهای فشاری را فعال کنید .
- حالتهای اجرای پسزمینه واکشی پسزمینه و اعلانهای از راه دور را فعال کنید.
کلید احراز هویت APN خود را آپلود کنید
قبل از استفاده از FCM، گواهینامه APN خود را در Firebase آپلود کنید. اگر قبلاً گواهینامه APN ندارید، در مرکز اعضای برنامهنویس Apple ایجاد کنید.
- در داخل پروژه خود در کنسول Firebase، نماد چرخ دنده را انتخاب کنید، تنظیمات پروژه را انتخاب کنید و سپس برگه Cloud Messaging را انتخاب کنید.
- دکمه آپلود گواهی را برای گواهی توسعه، گواهی تولید یا هر دو انتخاب کنید. حداقل یکی مورد نیاز است.
- برای هر گواهی، فایل .p12 را انتخاب کنید و در صورت وجود رمز عبور را وارد کنید. مطمئن شوید که شناسه بسته این گواهی با شناسه بسته برنامه شما مطابقت دارد. ذخیره را انتخاب کنید.
روش swizzling
برای استفاده از افزونه FCM Flutter در دستگاه های اپل، نباید Swizzling متد را غیرفعال کنید. Swizzling مورد نیاز است و بدون آن، ویژگیهای کلیدی Firebase مانند مدیریت توکن FCM به درستی کار نمیکنند.
اندروید
خدمات گوگل پلی
کلاینتهای FCM به دستگاههای دارای Android نسخه 4.4 یا بالاتر که سرویسهای Google Play را نیز نصب کردهاند، یا شبیهساز دارای Android 4.4 با Google API نیاز دارند. توجه داشته باشید که شما محدود به استقرار برنامه های اندروید خود از طریق فروشگاه Google Play نیستید.
برنامههایی که به Play Services SDK متکی هستند، باید همیشه قبل از دسترسی به ویژگیهای سرویسهای Google Play، دستگاه را برای یک APK سازگار با سرویسهای Google Play بررسی کنند. توصیه می شود این کار را در دو مکان انجام دهید: در متد onCreate()
اکتیویتی اصلی و در متد onResume()
آن. بررسی onCreate()
تضمین میکند که برنامه بدون بررسی موفقیتآمیز قابل استفاده نیست. بررسی onResume()
تضمین میکند که اگر کاربر از طریق روشهای دیگری مانند دکمه برگشت به برنامه در حال اجرا برگردد، بررسی همچنان انجام میشود.
اگر دستگاه نسخه سازگار خدمات Google Play را ندارد، برنامه شما میتواند با GoogleApiAvailability.makeGooglePlayServicesAvailable()
تماس بگیرد تا به کاربران اجازه دهد خدمات Google Play را از فروشگاه Play دانلود کنند.
وب
اعتبارنامه وب را با FCM پیکربندی کنید
رابط وب FCM از اعتبارنامههای وب به نام «شناسایی سرور برنامه داوطلبانه» یا کلیدهای «VAPID» استفاده میکند تا درخواستهای ارسال را به سرویسهای فشار وب پشتیبانیشده مجاز کند. برای اشتراک برنامه خود در اعلانهای فشاری، باید یک جفت کلید را با پروژه Firebase خود مرتبط کنید. می توانید یک جفت کلید جدید ایجاد کنید یا جفت کلید موجود خود را از طریق کنسول Firebase وارد کنید.
یک جفت کلید جدید ایجاد کنید
برگه Cloud Messaging را در قسمت تنظیمات کنسول Firebase باز کنید و به بخش پیکربندی وب بروید.
در برگه Web Push Certificates ، روی Generate Key Pair کلیک کنید. کنسول اعلامیه ای مبنی بر ایجاد جفت کلید نمایش می دهد و رشته کلید عمومی و تاریخ اضافه شده را نمایش می دهد.
یک جفت کلید موجود را وارد کنید
اگر یک جفت کلید موجود دارید که از قبل با برنامه وب خود استفاده میکنید، میتوانید آن را به FCM وارد کنید تا بتوانید از طریق APIهای FCM به نمونههای برنامه وب موجود خود دسترسی پیدا کنید. برای وارد کردن کلیدها، باید به پروژه Firebase در سطح مالک دسترسی داشته باشید. کلید عمومی و خصوصی موجود خود را در قالب کدگذاری شده امن URL base64 وارد کنید:
برگه Cloud Messaging را در قسمت تنظیمات کنسول Firebase باز کنید و به بخش پیکربندی وب بروید.
در برگه Web Push Certificates ، متن پیوند «وارد کردن یک جفت کلید موجود» را پیدا کرده و انتخاب کنید.
در گفتگوی وارد کردن جفت کلید ، کلیدهای عمومی و خصوصی خود را در فیلدهای مربوطه وارد کنید و روی واردات کلیک کنید. کنسول رشته کلید عمومی و تاریخ اضافه شدن را نمایش می دهد.
برای اطلاعات بیشتر در مورد قالب کلیدها و نحوه تولید آنها، به کلیدهای سرور برنامه مراجعه کنید.
افزونه FCM را نصب کنید
اگر قبلاً این کار را نکرده اید ، افزونه های Firebase را برای Flutter نصب و مقداردهی اولیه کنید .
از ریشه پروژه Flutter خود، دستور زیر را برای نصب افزونه اجرا کنید:
flutter pub add firebase_messaging
پس از تکمیل، برنامه Flutter خود را بازسازی کنید:
flutter run
به رمز ثبت نام دسترسی پیدا کنید
برای ارسال پیام به یک دستگاه خاص، باید رمز ثبت نام آن دستگاه را بدانید. از آنجایی که برای تکمیل این آموزش باید توکن را در قسمتی در کنسول Notifications وارد کنید، پس از بازیابی آن حتماً آن را کپی کنید یا به طور ایمن ذخیره کنید.
برای بازیابی رمز ثبت نام فعلی برای یک نمونه برنامه، getToken()
فراخوانی کنید. اگر مجوز اعلان داده نشده باشد، این روش از کاربر مجوزهای اعلان می خواهد. در غیر این صورت، توکن را برمی گرداند یا به دلیل خطا، آینده را رد می کند.
// You may set the permission requests to "provisional" which allows the user to choose what type
// of notifications they would like to receive once the user receives a notification.
final notificationSettings = await FirebaseMessaging.instance.requestPermission(provisional: true);
// For apple platforms, ensure the APNS token is available before making any FCM plugin API calls
final apnsToken = await FirebaseMessaging.instance.getAPNSToken();
if (apnsToken != null) {
// APNS token is available, make FCM plugin API requests...
}
در پلتفرم های وب، کلید عمومی VAPID خود را به getToken()
ارسال کنید:
final fcmToken = await FirebaseMessaging.instance.getToken(vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu");
برای اینکه هر زمان که توکن به روز می شود مطلع شوید، در جریان onTokenRefresh
مشترک شوید:
FirebaseMessaging.instance.onTokenRefresh
.listen((fcmToken) {
// TODO: If necessary send token to application server.
// Note: This callback is fired at each app startup and whenever a new
// token is generated.
})
.onError((err) {
// Error getting token.
});
جلوگیری از مقداردهی اولیه خودکار
هنگامی که یک نشانه ثبت FCM تولید می شود، کتابخانه شناسه و داده های پیکربندی را در Firebase آپلود می کند. اگر ترجیح می دهید از تولید خودکار توکن جلوگیری کنید، راه اندازی خودکار را در زمان ساخت غیرفعال کنید.
iOS
در iOS، یک مقدار فراداده به Info.plist
خود اضافه کنید:
FirebaseMessagingAutoInitEnabled = NO
اندروید
در Android، مجموعه 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" />
راه اندازی خودکار FCM را در زمان اجرا دوباره فعال کنید
برای فعال کردن راه اندازی خودکار برای یک نمونه برنامه خاص، setAutoInitEnabled()
را فراخوانی کنید:
await FirebaseMessaging.instance.setAutoInitEnabled(true);
پس از تنظیم، این مقدار در سراسر راه اندازی مجدد برنامه باقی می ماند.
مراحل بعدی
پس از راهاندازی برنامه سرویس گیرنده، آماده ارسال پیامهای پاییندستی با سازنده Notifications هستید. به ارسال یک پیام آزمایشی به یک برنامه پسزمینه مراجعه کنید.
برای افزودن سایر رفتارهای پیشرفته تر به برنامه خود، به اجرای سرور نیاز دارید.
سپس، در سرویس گیرنده برنامه خود:
،این مراحل را برای راه اندازی یک کلاینت FCM در Flutter دنبال کنید.
تنظیمات و الزامات پلتفرم خاص
برخی از مراحل مورد نیاز بستگی به پلتفرمی دارد که شما هدف آن قرار می دهید.
iOS+
قابلیت های برنامه را در Xcode فعال کنید
قبل از اینکه برنامه شما بتواند پیامها را دریافت کند، باید اعلانهای فشار و حالتهای پسزمینه را در پروژه Xcode خود فعال کنید.
- فضای کاری پروژه Xcode خود را باز کنید (
ios/Runner.xcworkspace
). - اعلانهای فشاری را فعال کنید .
- حالتهای اجرای پسزمینه واکشی پسزمینه و اعلانهای از راه دور را فعال کنید.
کلید احراز هویت APN خود را آپلود کنید
قبل از استفاده از FCM، گواهینامه APN خود را در Firebase آپلود کنید. اگر قبلاً گواهینامه APN ندارید، در مرکز اعضای برنامهنویس Apple ایجاد کنید.
- در داخل پروژه خود در کنسول Firebase، نماد چرخ دنده را انتخاب کنید، تنظیمات پروژه را انتخاب کنید و سپس برگه Cloud Messaging را انتخاب کنید.
- دکمه آپلود گواهی را برای گواهی توسعه، گواهی تولید یا هر دو انتخاب کنید. حداقل یکی مورد نیاز است.
- برای هر گواهی، فایل .p12 را انتخاب کنید و در صورت وجود رمز عبور را وارد کنید. مطمئن شوید که شناسه بسته این گواهی با شناسه بسته برنامه شما مطابقت دارد. ذخیره را انتخاب کنید.
روش swizzling
برای استفاده از افزونه FCM Flutter در دستگاه های اپل، نباید Swizzling متد را غیرفعال کنید. Swizzling مورد نیاز است و بدون آن، ویژگیهای کلیدی Firebase مانند مدیریت توکن FCM به درستی کار نمیکنند.
اندروید
خدمات گوگل پلی
کلاینتهای FCM به دستگاههای دارای Android نسخه 4.4 یا بالاتر که سرویسهای Google Play را نیز نصب کردهاند، یا شبیهساز دارای Android 4.4 با Google API نیاز دارند. توجه داشته باشید که شما محدود به استقرار برنامه های اندروید خود از طریق فروشگاه Google Play نیستید.
برنامههایی که به Play Services SDK متکی هستند، باید همیشه قبل از دسترسی به ویژگیهای سرویسهای Google Play، دستگاه را برای یک APK سازگار با سرویسهای Google Play بررسی کنند. توصیه می شود این کار را در دو مکان انجام دهید: در متد onCreate()
اکتیویتی اصلی و در متد onResume()
آن. بررسی onCreate()
تضمین میکند که برنامه بدون بررسی موفقیتآمیز قابل استفاده نیست. بررسی onResume()
تضمین میکند که اگر کاربر از طریق روشهای دیگری مانند دکمه برگشت به برنامه در حال اجرا برگردد، بررسی همچنان انجام میشود.
اگر دستگاه نسخه سازگار خدمات Google Play را ندارد، برنامه شما میتواند با GoogleApiAvailability.makeGooglePlayServicesAvailable()
تماس بگیرد تا به کاربران اجازه دهد خدمات Google Play را از فروشگاه Play دانلود کنند.
وب
اعتبارنامه وب را با FCM پیکربندی کنید
رابط وب FCM از اعتبارنامههای وب به نام «شناسایی سرور برنامه داوطلبانه» یا کلیدهای «VAPID» استفاده میکند تا درخواستهای ارسال را به سرویسهای فشار وب پشتیبانیشده مجاز کند. برای اشتراک برنامه خود در اعلانهای فشاری، باید یک جفت کلید را با پروژه Firebase خود مرتبط کنید. می توانید یک جفت کلید جدید ایجاد کنید یا جفت کلید موجود خود را از طریق کنسول Firebase وارد کنید.
یک جفت کلید جدید ایجاد کنید
برگه Cloud Messaging را در قسمت تنظیمات کنسول Firebase باز کنید و به بخش پیکربندی وب بروید.
در برگه Web Push Certificates ، روی Generate Key Pair کلیک کنید. کنسول اعلامیه ای مبنی بر ایجاد جفت کلید نمایش می دهد و رشته کلید عمومی و تاریخ اضافه شده را نمایش می دهد.
یک جفت کلید موجود را وارد کنید
اگر یک جفت کلید موجود دارید که از قبل با برنامه وب خود استفاده میکنید، میتوانید آن را به FCM وارد کنید تا بتوانید از طریق APIهای FCM به نمونههای برنامه وب موجود خود دسترسی پیدا کنید. برای وارد کردن کلیدها، باید به پروژه Firebase در سطح مالک دسترسی داشته باشید. کلید عمومی و خصوصی موجود خود را در قالب کدگذاری شده امن URL base64 وارد کنید:
برگه Cloud Messaging را در قسمت تنظیمات کنسول Firebase باز کنید و به بخش پیکربندی وب بروید.
در برگه Web Push Certificates ، متن پیوند «وارد کردن یک جفت کلید موجود» را پیدا کرده و انتخاب کنید.
در گفتگوی وارد کردن جفت کلید ، کلیدهای عمومی و خصوصی خود را در فیلدهای مربوطه وارد کنید و روی واردات کلیک کنید. کنسول رشته کلید عمومی و تاریخ اضافه شدن را نمایش می دهد.
برای اطلاعات بیشتر در مورد قالب کلیدها و نحوه تولید آنها، به کلیدهای سرور برنامه مراجعه کنید.
افزونه FCM را نصب کنید
اگر قبلاً این کار را نکرده اید ، افزونه های Firebase را برای Flutter نصب و مقداردهی اولیه کنید .
از ریشه پروژه Flutter خود، دستور زیر را برای نصب افزونه اجرا کنید:
flutter pub add firebase_messaging
پس از تکمیل، برنامه Flutter خود را بازسازی کنید:
flutter run
به رمز ثبت نام دسترسی پیدا کنید
برای ارسال پیام به یک دستگاه خاص، باید رمز ثبت نام آن دستگاه را بدانید. از آنجایی که برای تکمیل این آموزش باید توکن را در قسمتی در کنسول Notifications وارد کنید، پس از بازیابی آن حتماً آن را کپی کنید یا به طور ایمن ذخیره کنید.
برای بازیابی رمز ثبت نام فعلی برای یک نمونه برنامه، getToken()
فراخوانی کنید. اگر مجوز اعلان داده نشده باشد، این روش از کاربر مجوزهای اعلان می خواهد. در غیر این صورت، توکن را برمی گرداند یا به دلیل خطا، آینده را رد می کند.
// You may set the permission requests to "provisional" which allows the user to choose what type
// of notifications they would like to receive once the user receives a notification.
final notificationSettings = await FirebaseMessaging.instance.requestPermission(provisional: true);
// For apple platforms, ensure the APNS token is available before making any FCM plugin API calls
final apnsToken = await FirebaseMessaging.instance.getAPNSToken();
if (apnsToken != null) {
// APNS token is available, make FCM plugin API requests...
}
در پلتفرم های وب، کلید عمومی VAPID خود را به getToken()
ارسال کنید:
final fcmToken = await FirebaseMessaging.instance.getToken(vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu");
برای اینکه هر زمان که توکن به روز می شود مطلع شوید، در جریان onTokenRefresh
مشترک شوید:
FirebaseMessaging.instance.onTokenRefresh
.listen((fcmToken) {
// TODO: If necessary send token to application server.
// Note: This callback is fired at each app startup and whenever a new
// token is generated.
})
.onError((err) {
// Error getting token.
});
جلوگیری از مقداردهی اولیه خودکار
هنگامی که یک نشانه ثبت FCM تولید می شود، کتابخانه شناسه و داده های پیکربندی را در Firebase آپلود می کند. اگر ترجیح می دهید از تولید خودکار توکن جلوگیری کنید، راه اندازی خودکار را در زمان ساخت غیرفعال کنید.
iOS
در iOS، یک مقدار فراداده به Info.plist
خود اضافه کنید:
FirebaseMessagingAutoInitEnabled = NO
اندروید
در Android، مجموعه 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" />
راه اندازی خودکار FCM را در زمان اجرا دوباره فعال کنید
برای فعال کردن راه اندازی خودکار برای یک نمونه برنامه خاص، setAutoInitEnabled()
را فراخوانی کنید:
await FirebaseMessaging.instance.setAutoInitEnabled(true);
پس از تنظیم، این مقدار در سراسر راه اندازی مجدد برنامه باقی می ماند.
مراحل بعدی
پس از راهاندازی برنامه سرویس گیرنده، آماده ارسال پیامهای پاییندستی با سازنده Notifications هستید. به ارسال یک پیام آزمایشی به یک برنامه پسزمینه مراجعه کنید.
برای افزودن سایر رفتارهای پیشرفته تر به برنامه خود، به اجرای سرور نیاز دارید.
سپس، در سرویس گیرنده برنامه خود: