پوش نوتیفیکیشن در React Native؛ دریافت پیام و مدیریت توکن
پاسخ کوتاه: معماری درست برای پوش در React Native
برای ارسال پوش نوتیفیکیشن در یک اپلیکیشن React Native، خود React Native جایگزین سرویس‌های پوش بومی نیست. در اندروید باید از Firebase Cloud Messaging یا FCM و در iOS از Apple Push Notification service یا APNs استفاده کنید؛ سپس یک لایه بومی یا آداپتر نگه‌داری‌شده، دریافت رویدادها، نمایش اعلان، کلیک و به‌روزرسانی توکن را به کد جاوااسکریپت منتقل کند.
در این مقاله:
- پاسخ کوتاه: معماری درست برای پوش در React Native
- نقش FCM، APNs و آداپتر React Native
- پیش‌نیازهای اندروید و iOS
- چرخه عمر برنامه و انواع پیام
- مدیریت توکن، هویت کاربر و امنیت
- اتصال اختیاری به پوشفا
- چک‌لیست آزمایش و عیب‌یابی
- پرسش‌های متداول
اگر هدف شما استفاده از پوشفا است، مسیر قابل اتکا این است که ابتدا اتصال بومی FCM و APNs را طبق مستندات نسخه فعلی آداپتر مورد پشتیبانی سرویس راه‌اندازی کنید و بعد شناسه یا توکن دستگاه را از اپلیکیشن به بک‌اند خود بفرستید. از نصب نام پکیج‌ها یا فراخوانی متدهایی که در پنل و مستندات رسمی پروژه شما وجود ندارند خودداری کنید؛ نام کتابخانه در نسخه‌های مختلف React Native و ابزارهای بومی می‌تواند تغییر کند.
نقش FCM، APNs و آداپتر React Native
FCM و APNs مسیر انتقال پیام را فراهم می‌کنند، اما مسئولیت‌های اپلیکیشن به همین‌جا ختم نمی‌شود. برنامه باید مجوز اعلان را بگیرد، توکن را دریافت و ثبت کند، در وضعیت‌های مختلف اجرا رویداد مناسب را پردازش کند و هنگام کلیک، کاربر را به مقصد درست ببرد. آداپتر React Native این مرز میان کد جاوااسکریپت و APIهای نیتیو را ساده می‌کند؛ بااین‌حال تنظیمات پروژه، شناسه بسته، امضای اپلیکیشن و قابلیت‌های هر سیستم‌عامل همچنان باید جداگانه بررسی شوند.
در اندروید، از نسخه ۱۳ به بعد مجوز نمایش اعلان در زمان اجرا اهمیت دارد. از اندروید ۸ نیز هر اعلان به یک کانال تعلق دارد و کاربر می‌تواند تنظیمات همان کانال را مستقل تغییر دهد. بنابراین ساخت کانال، نام مناسب، اهمیت اعلان و رفتار صدای آن را پیش از انتشار مشخص کنید. راهنمای رسمی مجوز اعلان اندروید در مستندات Android توضیح داده شده است.
در iOS باید قابلیت Push Notifications و تنظیمات APNs برای شناسه برنامه فعال باشد و برنامه پس از دریافت اجازه، برای دریافت اعلان از سیستم ثبت‌نام کند. وضعیت شبیه‌ساز، محیط توسعه و نسخه تولید را جداگانه آزمایش کنید؛ توکن یا اعتبارنامه یک محیط را نباید به‌عنوان توکن محیط دیگر فرض کرد.
پیش‌نیازهای اندروید و iOS
اندروید
- شناسه بسته اندروید را با پروژه Firebase و تنظیمات انتشار برنامه هماهنگ کنید.
- فایل تنظیمات FCM را فقط در محل مورد نیاز پروژه قرار دهید و آن را در مخزن عمومی منتشر نکنید.
- برای نسخه‌های جدید اندروید، درخواست مجوز اعلان را در زمان مناسبی از جریان کاربر انجام دهید؛ بهتر است قبل از درخواست، ارزش اعلان‌ها را کوتاه توضیح دهید.
- کانال‌های اعلان را با شناسه‌های ثابت بسازید. تغییر شناسه کانال می‌تواند تنظیمات قبلی کاربر را بی‌اثر کند.
iOS
- شناسه Bundle و محیط APNs را بررسی کنید و قابلیت اعلان را در تنظیمات پروژه فعال کنید.
- درخواست مجوز را در نقطه‌ای انجام دهید که کاربر دلیل آن را می‌فهمد، نه بلافاصله پس از نصب.
- ثبت موفق برنامه در APNs، دریافت توکن و ارسال آن به سرور را در لاگ‌های توسعه بررسی کنید.
- برای اعلان‌های دارای صدا، نشان و متن، تنظیمات نیتیو و داده پیام را با نیاز محصول هماهنگ کنید.
در هر دو سیستم‌عامل، مجوز ردشده، اعلان‌های خاموش، حالت تمرکز، حذف برنامه و نصب دوباره را جزو سناریوهای عادی بدانید؛ این وضعیت‌ها خطای موقتی شبکه محسوب نمی‌شوند.
چرخه عمر برنامه و انواع پیام
رفتار پیام به وضعیت برنامه وابسته است. وقتی اپلیکیشن در پیش‌زمینه است، معمولاً باید رویداد دریافت را در کد خود پردازش کنید و در صورت نیاز اعلان محلی یا رابط کاربری داخل برنامه نشان دهید. وقتی برنامه در پس‌زمینه یا بسته است، سیستم‌عامل و نوع پیام تعیین می‌کنند چه بخشی اجرا شود. برای همین، یک کد واحد که در همه وضعیت‌ها انتظار رفتار یکسان دارد، قابل اعتماد نیست.
پیام اعلان معمولاً برای نمایش مستقیم مناسب است، درحالی‌که پیام داده‌ای برای رساندن داده به منطق برنامه به کار می‌رود. محدودیت‌های اجرای پس‌زمینه، به‌خصوص در iOS، اجازه نمی‌دهد از پوش برای اجرای نامحدود یا همگام‌سازی تضمین‌شده استفاده کنید. ارسال داده حساس در متن پیام نیز مناسب نیست؛ پیام را کوتاه نگه دارید و اطلاعات اصلی را پس از باز شدن امن برنامه دریافت کنید.
نمایش موفق اعلان فقط یعنی سیستم یا لایه دریافت توانسته است آن را نشان دهد؛ این رویداد اثبات نمی‌کند کاربر پیام را دیده یا خوانده است. برای کلیک، مقصد را با شناسه‌ای قابل اعتبارسنجی باز کنید و در صورت استفاده از لینک وب، داده شخصی را در نشانی قرار ندهید.
در مورد وب، React web با React Native یکی نیست. سرویس‌ورکر و فایل ریشه pushfa-messaging-sw.js مربوط به یکپارچه‌سازی وب پوش هستند و نباید آن را به‌عنوان راهکار مستقیم اپلیکیشن موبایل استفاده کرد. برای تفاوت معماری وب و اپلیکیشن، راهنمای تفاوت وب پوش و پوش اپلیکیشن را ببینید.
مدیریت توکن، هویت کاربر و امنیت
توکن دستگاه ممکن است تغییر کند؛ برای نمونه پس از نصب دوباره، تغییر وضعیت برنامه یا تغییرات سرویس بومی. در زمان دریافت توکن جدید، آن را با شناسه کاربر و مشخصات پلتفرم به بک‌اند ارسال و رکورد قبلی را به‌روزرسانی کنید. یک کاربر ممکن است هم‌زمان چند دستگاه و چند توکن فعال داشته باشد.
در بک‌اند، برای هر توکن وضعیت فعال، آخرین زمان مشاهده، سیستم‌عامل و نسخه برنامه را نگه دارید. هنگام خطای دائمی یا لغو مجوز، توکن را غیرفعال کنید، اما خطای موقتی شبکه را فوراً به حذف رکورد تعبیر نکنید. اگر کاربر از حساب خارج شد، ارتباط توکن با حساب را طبق سیاست حریم خصوصی محصول قطع کنید.
- کلید خصوصی، اعتبارنامه FCM/APNs و کلید خصوصی پوشفا فقط در سرور یا محیط امن CI نگه‌داری شوند.
- کد موبایل محل ارسال کمپین نیست. اپلیکیشن نباید اعتبارنامه ارسال را درون خود داشته باشد.
- توکن را داده حساس عملیاتی بدانید. آن را در لاگ عمومی، ابزار تحلیل یا URL قرار ندهید.
- شناسه کاربر و توکن را جدا نگه دارید. حذف حساب باید تکلیف توکن‌های وابسته را نیز مشخص کند.
جزئیات کانال‌ها و تنظیمات اعلان اندروید را می‌توانید در راهنمای کانال اعلان اندروید مرور کنید.
اتصال اختیاری به پوشفا
پوشفا از FCM استفاده می‌کند و قابلیت‌هایی مانند موضوع‌ها، نگه‌داری توکن مشترکان، نام مستعار، گزارش ارسال و کلیک و APIهای سمت سرور را ارائه می‌دهد. بنابراین می‌توانید یک لایه سرویس در بک‌اند بسازید که توکن‌های اپلیکیشن را ثبت کند، مخاطب را به شناسه مشترک یا ساختار کاربری خود مرتبط سازد و ارسال‌ها را از پنل یا سرور مدیریت کند.
برای React Native، فقط از آداپتر پلتفرمی نگه‌داری‌شده‌ای استفاده کنید که نسخه آن در مستندات رسمی یا پنل سرویس برای پروژه شما معرفی شده است. راهنمای نصب را دقیقاً با نسخه React Native، Gradle، Xcode و iOS پروژه تطبیق دهید. ادعای وجود یک بسته npm یا متد عمومی بدون بررسی مستندات می‌تواند پروژه را به وابستگی نادرست قفل کند.
کلید عمومی سرویس، در صورت نیاز آداپتر، باید از مسیر رسمی و متناسب با اپلیکیشن تنظیم شود؛ کلید خصوصی برای ارسال سروری است و نباید در فایل جاوااسکریپت، APK یا IPA قرار گیرد. اگر ارسال از بک‌اند خودتان انجام می‌شود، اعتبارسنجی کاربر، محدودیت نرخ، ثبت نتیجه ارسال و کنترل دسترسی را در همان بک‌اند پیاده کنید. برای جزئیات API سروری، به راهنمای ارسال سروری با PHP و Laravel مراجعه کنید.
اگر از موضوع‌ها یا شناسه‌های فشرده‌سازی استفاده می‌کنید، معنای آن را در FCM، APNs و لایه نمایش جداگانه بررسی کنید. فشرده‌سازی حمل‌ونقل الزاماً به معنی جایگزین‌شدن اعلان‌های نمایش‌داده‌شده روی دستگاه نیست.
چک‌لیست آزمایش و عیب‌یابی
- ثبت‌نام اولیه، رد مجوز و فعال‌کردن دوباره مجوز از تنظیمات سیستم را آزمایش کنید.
- دریافت توکن جدید و ارسال آن به بک‌اند را با یک شناسه کاربر آزمایشی بررسی کنید.
- پیام را در چهار وضعیت پیش‌زمینه، پس‌زمینه، بسته‌بودن و اجرای دوباره برنامه تست کنید.
- در اندروید ۱۳، کانال اعلان و مجوز runtime را جداگانه کنترل کنید.
- در iOS، محیط توسعه و تولید و همچنین حالت تمرکز یا خاموش‌بودن اعلان را بررسی کنید.
- روی کلیک اعلان، مقصد درست، بازشدن حساب کاربر و رفتار لینک منقضی را تست کنید.
- برای هر پیام یک شناسه داخلی ثبت کنید تا گزارش ارسال، نمایش احتمالی و کلیک با هم اشتباه نشوند.
- قطع شبکه، تأخیر طولانی، حذف برنامه و توکن نامعتبر را شبیه‌سازی کنید؛ TTL فقط مدت انتظار برای تحویل را محدود می‌کند و تضمین تحویل پس از بازگشت دستگاه نیست.
اگر ارسال موفق گزارش می‌شود اما چیزی دیده نمی‌شود، ابتدا مجوز و کانال را بررسی کنید، سپس وضعیت برنامه و نوع پیام را. اگر توکن ثبت نمی‌شود، شناسه پروژه، تنظیمات محیط، زمان درخواست مجوز و لاگ آداپتر را مقایسه کنید. برای خطاهای رایج تحویل، راهنمای عیب‌یابی دریافت‌نشدن پوش نیز مفید است.
پرسش‌های متداول
آیا React Native به‌تنهایی پوش را ارسال می‌کند؟
خیر. React Native لایه مشترک برنامه را فراهم می‌کند، اما ارسال و دریافت به FCM، APNs و تنظیمات نیتیو هر پلتفرم وابسته است.
آیا می‌توان کلید خصوصی ارسال را داخل اپلیکیشن گذاشت؟
خیر. هر چیزی که در APK یا IPA قرار گیرد قابل استخراج است. ارسال و نگه‌داری کلیدهای خصوصی باید در بک‌اند انجام شود.
آیا یک توکن برای اندروید و iOS کافی است؟
خیر. توکن‌ها به پلتفرم و محیط وابسته‌اند. برای هر نصب و هر سیستم‌عامل رکورد جداگانه نگه دارید.
آیا نمایش اعلان به معنی خوانده‌شدن آن است؟
خیر. نمایش موفق فقط یک رویداد فنی است. خواندن یا تعامل کاربر را باید با کلیک یا رویداد قابل اندازه‌گیری دیگری، با رعایت حریم خصوصی، جداگانه تحلیل کنید.