فعال‌سازی پوش نوتیفیکیشن در سایت؛ نصب و بررسی سرویس‌ورکر
برای فعال‌کردن پوش نوتیفیکیشن در سایت، ابتدا سایت را روی HTTPS اجرا کنید، فایل سرویس‌ورکر را در ریشه همان دامنه قرار دهید و درخواست اجازه اعلان را فقط پس از یک اقدام مستقیم کاربر نمایش دهید. در مسیر ساده‌تر، کد ادغام و کلید عمومی سرویس پوشفا را از پنل دریافت می‌کنید و نباید هیچ کلید خصوصی یا اعتبارنامه سرور را در کد مرورگر قرار دهید.
در این مقاله:
- پیش‌نیازهای فنی و تصمیم درباره روش اجرا
- اتصال سایت به پوشفا
- درخواست اجازه و تجربه کاربر
- رفتار مرورگرها و حالت‌های دریافت پیام
- تست، گزارش و عیب‌یابی
- چک‌لیست انتشار
- پرسش‌های رایج
این راهنما برای صاحب سایت و توسعه‌دهنده نوشته شده است: از آماده‌سازی دامنه تا تست پیام در حالت باز و پس‌زمینه، کنترل scope، بررسی سیاست امنیت محتوا و شناخت محدودیت‌های iOS.
پیش‌نیازهای فنی و تصمیم درباره روش اجرا
سرویس‌ورکر، اسکریپت پس‌زمینه‌ای مرورگر، روی یک منشأ امن اجرا می‌شود؛ برای سایت عمومی یعنی HTTPS. در محیط توسعه، localhost معمولاً برای آزمایش منشأ امن محسوب می‌شود، اما این استثنا جایگزین گواهی معتبر در محیط واقعی نیست.
- دامنه یکسان: صفحه سایت، فایل سرویس‌ورکر و اسکریپت ادغام باید از همان منشأ بارگذاری شوند؛ تفاوت دامنه یا پروتکل می‌تواند ثبت سرویس‌ورکر را مختل کند.
- دسترسی به ریشه: فایل سرویس‌ورکر باید در مسیری مانند
/pushfa-messaging-sw.jsقرار گیرد تا scope پیش‌فرض آن کل سایت باشد. - پاسخ درست سرور: فایل باید با وضعیت HTTP موفق، محتوای واقعی جاوااسکریپت و MIME مناسب مانند
application/javascriptارائه شود؛ پاسخ HTML صفحه خطا به‌جای فایل، ثبت سرویس‌ورکر را شکست می‌دهد. - سیاست امنیت محتوا: اگر سایت CSP دارد، مبدأهای لازم برای اسکریپت و ارتباط سرویس را طبق راهنمای همان سرویس در
script-srcوconnect-srcبررسی کنید. از بازکردن بی‌دلیل دسترسی‌ها با*پرهیز کنید.
دو مسیر کلی وجود دارد: پیاده‌سازی مستقل با Push API و زیرساخت سرور خودتان، یا استفاده از سرویس آماده. مسیر مستقل کنترل بیشتری می‌دهد، اما نگهداری اشتراک‌ها، رمزنگاری، وضعیت توکن‌ها و سازگاری مرورگرها را نیز به تیم شما واگذار می‌کند. برای بیشتر سایت‌های محتوایی و فروشگاهی، سرویس آماده زمان و ریسک عملیاتی کمتری دارد.
برای آشنایی با اجزای فنی تحویل پیام می‌توانید به راهنمای زیرساخت فنی وب‌پوش مراجعه کنید.
اتصال سایت به پوشفا
در پنل پوشفا یک سرویس وب بسازید و بخش ادغام سایت را باز کنید. کد جاوااسکریپت و فایل ریشه‌ای ارائه‌شده در همان پنل به سرویس شما وابسته‌اند؛ بنابراین کد را از مستندات پراکنده یا نمونه‌های حدسی کپی نکنید.
- کد ادغام را عیناً از پنل دریافت و در قالب اصلی سایت، معمولاً بخش head یا محل توصیه‌شده در پنل، قرار دهید.
- فایل
pushfa-messaging-sw.jsرا بدون تغییر نام یا محتوای خودسرانه در ریشه دامنه عمومی آپلود کنید. - اطمینان دهید URL فایل با دامنه صفحه یکی است؛ برای نمونه، صفحه
https://example.comنباید سرویس‌ورکر را از زیر دامنه یا دامنه دیگری بارگیری کند. - در تنظیمات سایت، کلید سرویس عمومی را استفاده کنید. کلید خصوصی برای ارسال از سمت سرور است و نباید در HTML، جاوااسکریپت، مخزن عمومی یا اپ موبایل قرار بگیرد.
- پس از انتشار، در مرورگر یک بار با پاک‌سازی کش یا بازنشانی سرویس‌ورکر بررسی کنید که فایل جدید واقعاً دریافت شده است.
پوشفا از FCM برای مسیر ارسال استفاده می‌کند و می‌تواند مشترک‌ها، توکن‌های ذخیره‌شده، نام مستعارها، موضوع‌ها و گزارش‌های ارسال و کلیک را مدیریت کند. موضوع‌ها برای گروه‌بندی کاربرد دارند؛ مثلاً می‌توان مشترک‌های علاقه‌مند به «تخفیف» را جدا از مشترک‌های «محتوای آموزشی» نگه داشت. منطق عضویت، خروج و نام‌گذاری موضوع‌ها را در backend خودتان مستند کنید تا تغییرات کمپین باعث عضویت ناخواسته نشود.
اگر ارسال باید از سامانه داخلی شما انجام شود، اعتبارنامه خصوصی و فراخوانی API را فقط در backend نگه دارید. مرورگر باید صرفاً با کلید عمومی و کد ادغام سرویس کار کند؛ هر راهکاری که کلید خصوصی را به کاربر تحویل دهد، طراحی امنی نیست.
درخواست اجازه و تجربه کاربر
درخواست اجازه اعلان را هنگام بارگذاری نخستین صفحه نمایش ندهید. ابتدا یک توضیح کوتاه و قابل‌فهم در رابط سایت نشان دهید و پس از کلیک کاربر روی گزینه‌ای مانند «اطلاع از وضعیت سفارش» یا «دریافت خبرهای جدید»، درخواست بومی مرورگر را آغاز کنید. این اقدام هم با محدودیت مرورگرها سازگارتر است و هم به کاربر می‌گوید چرا اعلان می‌خواهد.
- ارزش اعلان را مشخص کنید؛ برای نمونه، «اعلام موجودشدن کالا» از عبارت مبهم «فعال‌سازی اعلان‌ها» روشن‌تر است.
- تعداد یا نوع پیام‌ها را صادقانه توضیح دهید و راه لغو اشتراک را پنهان نکنید.
- اگر کاربر قبلاً اجازه را رد کرده است، او را به تنظیمات مرورگر راهنمایی کنید؛ نمایش مکرر همان درخواست معمولاً دوباره پنجره بومی را باز نمی‌کند.
- اطلاعات شخصی را در متن اعلان یا URL قرار ندهید. برای سنجش کمپین، از برچسب‌های UTM غیرشخصی و سازگار استفاده کنید.
در iOS و iPadOS، وب‌اپ باید ابتدا به صفحه اصلی افزوده شود و درخواست اجازه نیز از یک اقدام مستقیم کاربر در همان وب‌اپ آغاز شود. این قابلیت برای Home Screen web appهای iOS/iPadOS 16.4 و بعد از آن مطرح است، نه هر تب عادی مرورگر؛ جزئیات رسمی در توضیح WebKit درباره Web Push در iOS و iPadOS آمده است.
رفتار مرورگرها و حالت‌های دریافت پیام
در حالت پیش‌زمینه، صفحه باز است و کد صفحه یا SDK می‌تواند رویداد دریافت پیام را طبق پیاده‌سازی سرویس مدیریت کند. در حالت پس‌زمینه یا بسته‌بودن صفحه، سرویس‌ورکر مسیر دریافت و نمایش اعلان را بر عهده می‌گیرد. این دو مسیر الزاماً رفتار یکسانی ندارند؛ نمایش، کلیک و بازکردن لینک را در هر دو حالت جداگانه آزمایش کنید.
برای وب‌پوش در Safari، اعلان قابل‌مشاهده بخشی از مدل دریافت است؛ طراحی پیام به‌گونه‌ای که عمداً هیچ اعلان قابل‌مشاهده‌ای نشان ندهد، توصیه عمومی قابل اتکایی نیست. همچنین موفقیت نمایش اعلان فقط نشان می‌دهد مرورگر به مرحله showNotification رسیده است و ثابت نمی‌کند کاربر آن را دیده یا خوانده است.
در اندروید نیز اجازه اعلان و تنظیمات کانال می‌تواند توسط کاربر تغییر کند. بنابراین خاموش‌بودن اعلان، بی‌صدابودن کانال یا محدودیت سیستم‌عامل را در کنار وضعیت ارسال سرویس بررسی کنید، نه اینکه همه موارد را به خرابی سرور نسبت دهید.
برای زمان نگهداری پیام در حالت آفلاین، TTL به معنی نگهداری نامحدود یا تضمین تحویل نیست. سرویس‌های انتقال ممکن است پیام منقضی‌شده را حذف کنند و رفتار پیام‌های قابل‌جایگزینی نیز با جایگزینی اعلان نمایش‌داده‌شده یکسان نیست. جزئیات این تفاوت را در راهنمای وب‌پوش در حالت آفلاین ببینید.
تست، گزارش و عیب‌یابی
تست را با یک دستگاه و یک مرورگر شروع کنید و بعد به ماتریس مرورگرها و دستگاه‌های واقعی گسترش دهید. در ابزارهای توسعه‌دهنده، بخش Application و Service Workers را باز کنید و این موارد را بررسی کنید:
- فایل سرویس‌ورکر با وضعیت موفق دریافت شده و در حالت فعال قرار دارد.
- scope شامل صفحه‌ای است که کاربر از آن عضو می‌شود.
- درخواست ثبت فایل، پاسخ HTML، خطای MIME یا خطای CSP ندارد.
- مجوز اعلان در تنظیمات مرورگر روی حالت مجاز است.
- یک پیام آزمایشی در حالت باز، پس‌زمینه و پس از بستن تب بررسی شده است.
- کلیک اعلان لینک درست را باز می‌کند و اگر صفحه از قبل باز است، رفتار مورد انتظار مانند تمرکز پنجره رخ می‌دهد.
اگر سرویس‌ورکر ثبت نمی‌شود، URL فایل را مستقیم باز کنید و وضعیت پاسخ، نوع محتوا و لاگ کنسول را ببینید. اگر ثبت موفق است اما اعلان نمی‌آید، مجوز مرورگر، تنظیمات سیستم‌عامل، scope و مسیر پس‌زمینه را جداگانه بررسی کنید. اگر ارسال در پنل موفق گزارش شده ولی کاربر چیزی نمی‌بیند، موفقیت ارسال را با موفقیت نمایش اعلان یکی ندانید.
گزارش کلیک برای سنجش تعامل مفید است، اما گزارش تحویل یا نمایش به معنی خواندن پیام نیست. در تحلیل کمپین، این مراحل را جدا نگه دارید: درخواست ارسال، پذیرش توسط مسیر انتقال، نمایش اعلان و کلیک کاربر.
چک‌لیست انتشار
- HTTPS روی نسخه نهایی دامنه فعال است و تغییر مسیرهای HTTP به HTTPS درست کار می‌کنند.
- کد پنل با کلید عمومی در سایت قرار گرفته و هیچ راز خصوصی در مرورگر وجود ندارد.
- فایل
pushfa-messaging-sw.jsدر ریشه، با MIME جاوااسکریپت و از همان origin قابل دریافت است. - scope، CSP، کش CDN و قوانین امنیتی سرور بررسی شده‌اند.
- درخواست اجازه پس از کلیک کاربر و با توضیح روشن نمایش داده می‌شود.
- سناریوهای پیش‌زمینه، پس‌زمینه، دستگاه آفلاین و کلیک اعلان آزمایش شده‌اند.
- برای iOS، راهنمای افزودن سایت به Home Screen و سپس فعال‌سازی اعلان آماده است.
- موضوع‌ها و نام مستعارها با یک الگوی ثابت مدیریت می‌شوند و کاربران پیام نامرتبط دریافت نمی‌کنند.
- UTMها فاقد اطلاعات شخصی هستند و گزارش‌های ارسال و کلیک جداگانه تفسیر می‌شوند.
پرسش‌های رایج
آیا می‌توان فایل سرویس‌ورکر را در یک پوشه معمولی گذاشت؟
می‌توان، اما scope پیش‌فرض فقط همان پوشه و زیرمسیرهایش را پوشش می‌دهد. برای پوشش کل سایت، قرار دادن فایل ارائه‌شده در ریشه ساده‌ترین انتخاب است؛ تغییر مسیر یا هدر گسترش‌دهنده باید فقط با آگاهی از تنظیمات سرور انجام شود.
آیا درخواست اجازه را می‌توان خودکار بعد از ورود کاربر اجرا کرد؟
بهتر است نه. درخواست را به یک اقدام مستقیم مانند کلیک کاربر وصل کنید و پیش از آن توضیح کوتاه نمایش دهید. اجرای خودکار روی بارگذاری صفحه در برخی مرورگرها محدود یا بی‌اثر می‌شود.
اگر پیام در پنل ارسال شد اما روی گوشی دیده نشد، مشکل از کجاست؟
مجوز اعلان، وضعیت کانال، حالت آفلاین، انقضای مسیر انتقال، scope و ثبت سرویس‌ورکر را بررسی کنید. گزارش ارسال به‌تنهایی تضمین نمی‌کند اعلان روی صفحه نمایش داده شده یا کاربر آن را خوانده است.
آیا کلید خصوصی سرویس را می‌توان در اپ یا کد frontend قرار داد؟
خیر. کلید خصوصی و هر اعتبارنامه ارسال باید فقط در backend یا محیط امن سرور نگهداری شود. frontend تنها باید از کلید عمومی و کد ادغام مورد نیاز اشتراک استفاده کند.