ورود شروع رایگان
بازگشت به وبلاگ

چرا پوش نوتیفیکیشن دریافت نمی‌شود؟ راهنمای عیب‌یابی وب پوش

۱۴۰۴-۰۵-۱۲ احسان
چرا پوش نوتیفیکیشن دریافت نمی‌شود؟ راهنمای عیب‌یابی وب پوش

اگر وب‌پوش ارسال شده اما در مقصد دیده نمی‌شود، از پاک‌کردن داده‌های مرورگر یا ارسال دوباره شروع نکنید. ابتدا مشخص کنید پیام در کدام نقطه متوقف شده است: پذیرش درخواست ارسال، معتبر بودن اشتراک و توکن، اجرای سرویس‌ورکر، مجوز اعلان، وضعیت سیستم‌عامل و شبکه، یا نمایش واقعی اعلان. هیچ راه‌حل واحدی برای همه مرورگرها و دستگاه‌ها وجود ندارد؛ تشخیص مرحله‌ی شکست، مسیر اصلاح را کوتاه می‌کند.

در این مقاله:

Sent، Delivered و نمایش واقعی چه تفاوتی دارند؟

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

برای تحلیل، این سه رویداد را جدا ثبت کنید:

  • پذیرش ارسال: سامانه درخواست را با داده‌های قابل‌قبول دریافت کرده است.
  • تحویل به مسیر مرورگر یا دستگاه: پیام به اشتراک معتبر رسیده یا برای تحویل در مسیر قرار گرفته است.
  • تأیید نمایش: سرویس‌ورکر با موفقیت showNotification را اجرا کرده است.

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

درخت تشخیص را به همین ترتیب اجرا کنید

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

مرحلهپرسش اصلینشانه‌ی مشکل
۱. پذیرش ارسالآیا درخواست با وضعیت معتبر پذیرفته و در صورت نیاز زمان‌بندی شده است؟خطای اعتبارسنجی، صف ناموفق یا نبودن شناسه پیام
۲. اشتراک و توکنآیا گیرنده همان اشتراک فعال و معتبر است؟شناسه اشتباه، اشتراک حذف‌شده یا توکن منقضی
۳. سرویس‌ورکرآیا فایل worker در دامنه و محدوده‌ی درست ثبت شده است؟خطای ثبت، پاسخ HTML یا خطای رویداد push
۴. مجوزآیا مرورگر و سیستم‌عامل اجازه‌ی اعلان دارند؟مجوز مسدود، لغوشده یا درخواست‌نشده
۵. دستگاه، شبکه و TTLآیا دستگاه آنلاین و پیام هنوز معتبر است؟حالت آفلاین، محدودیت باتری، انقضای TTL یا اختلال شبکه
۶. نمایش و تأییدآیا worker واقعاً اعلان را ساخته است؟اجرای ناقص showNotification یا نبودن گزارش نمایش

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

اعتبار اشتراک و توکن را بررسی کنید

بازشدن سایت یا مشاهده‌ی پنجره‌ی عضویت به معنی فعال‌بودن اشتراک نیست. پس از عضویت، مرورگر یک اشتراک ایجاد می‌کند و سامانه آن را با شناسه‌ای مانند توکن ذخیره‌شده مرتبط می‌کند. تغییر مرورگر، پاک‌شدن داده‌ها، لغو مجوز یا بازنشستگی توکن می‌تواند باعث شود ارسال به شناسه‌ای قدیمی انجام شود.

  • بررسی کنید پیام دقیقاً به همان اشتراک آزمایشی ارسال شده، نه فقط به یک موضوع یا گروه دیگر.
  • زمان ایجاد یا آخرین به‌روزرسانی اشتراک را با زمان بروز مشکل مقایسه کنید.
  • اگر کاربر مجوز را لغو و دوباره فعال کرده، اشتراک جدید را ثبت و اشتراک قدیمی را غیرفعال کنید.
  • توکن کامل و کلیدهای دسترسی را در گزارش عمومی، تیکت یا کد سمت مرورگر قرار ندهید.

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

سرویس‌ورکر و مسیر نمایش را تست کنید

سرویس‌ورکر باید از مسیر درست و در محدوده‌ای ثبت شود که صفحه و اشتراک شما را پوشش می‌دهد. اگر آدرس فایل به‌جای جاوااسکریپت، صفحه‌ی ورود یا سند HTML برگرداند، ثبت worker ممکن است شکست بخورد یا رویداد push به کد مورد انتظار نرسد.

در پنل سرویس، فایل ریشه‌ی pushfa-messaging-sw.js و قطعه‌کد دقیق همان پنل را دریافت و استفاده کنید. نام بسته، تابع یا نمونه‌ی SDK حدسی را جایگزین کد ارائه‌شده نکنید. کلید عمومی سرویس برای راه‌اندازی سمت کاربر است؛ کلید خصوصی باید فقط در سرور بماند.

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

  • ثبت موفق worker و scope آن؛
  • کد پاسخ و نوع محتوای فایل worker؛
  • خطاهای رویداد دریافت پیام؛
  • ساخته‌شدن عنوان، متن و لینک اعلان؛
  • اجرای موفق showNotification و خطای احتمالی Promise.

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

مجوز مرورگر و محدودیت‌های iOS را جداگانه کنترل کنید

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

در آیفون و آیپد، وب‌پوش برای وب‌اپی که به صفحه‌ی اصلی افزوده شده، از iOS و iPadOS 16.4 به بعد قابل درخواست است و درخواست باید پس از اقدام مستقیم کاربر انجام شود. تب معمولی سایت را با وب‌اپ نصب‌شده روی Home Screen یکی نگیرید. جزئیات این محدودیت‌ها در توضیح WebKit درباره وب‌پوش iOS و iPadOS آمده است.

در اندروید نیز مجوز اعلان و تنظیمات کانال اعلان می‌توانند مستقل از اشتراک مرورگر باشند. نام کانال، سطح اهمیت، بی‌صداشدن آن و تنظیمات مزاحم‌نشدن را روی همان دستگاه بررسی کنید. نتیجه‌ی تست را با دستگاهی که قبلاً اعلان را دریافت کرده مقایسه کنید، نه فقط با شبیه‌ساز.

شبکه، حالت آفلاین و TTL را بررسی کنید

دستگاه برای دریافت پیام به مسیر ارتباطی سرویس پوش نیاز دارد؛ بازشدن یک صفحه‌ی وب به‌تنهایی سلامت این مسیر را ثابت نمی‌کند. شبکه‌ی سازمانی، فیلتر، VPN، محدودیت باتری و توقف فعالیت پس‌زمینه می‌توانند زمان تحویل را تغییر دهند.

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

اگر چند پیام هم‌زمان می‌فرستید، collapse را با جایگزینی اعلان روی صفحه یکی ندانید. ادغام پیام‌های در انتظار در مسیر انتقال با به‌روزرسانی اعلان قبلی، دو رفتار متفاوت‌اند و ممکن است میان پلتفرم‌ها یکسان عمل نکنند.

نمایش اعلان و گزارش را تأیید کنید

در آخرین مرحله، یک اعلان ساده با عنوان و متن کوتاه بفرستید و لاگ worker را بررسی کنید. در Pushfa، گزارش تحویل و کلیک برای تحلیل مسیر مفیدند، اما گزارش کلیک فقط تعامل بعدی کاربر را نشان می‌دهد. نبودن کلیک به معنی نرسیدن نیست و ثبت نمایش نیز به معنی خوانده‌شدن نیست.

برای آزمایش، از متن‌هایی در محدوده‌ی فنی سرویس استفاده کنید: عنوان حداکثر ۳۵ نویسه و متن حداکثر ۱۵۰ نویسه. لینک را ابتدا با یک نشانی ساده و معتبر تست کنید و بعد سراغ پارامترهای کمپین بروید. در URL از داده‌ی شخصی استفاده نکنید.

اگر worker اجرای موفق showNotification را ثبت می‌کند اما کاربر چیزی نمی‌بیند، تنظیمات اعلان، کانال، Focus، مزاحم‌نشدن و وضعیت مرکز اعلان سیستم‌عامل را بررسی کنید. اگر اجرای worker نیز ثبت نمی‌شود، به مرحله‌ی اشتراک یا worker برگردید؛ ارسال‌های بیشتر بدون رفع آن مرحله اطلاعات تازه‌ای ایجاد نمی‌کنند.

پرسش‌های متداول

آیا وضعیت Sent یعنی اعلان حتماً نمایش داده شده است؟

خیر. Sent بیشتر نشان‌دهنده‌ی پذیرش یا ورود درخواست به مسیر ارسال است. برای نمایش باید اشتراک، worker، مجوز و شرایط دستگاه نیز درست باشند.

آیا بازکردن سایت باعث دریافت پیام‌های قبلی می‌شود؟

نه لزوماً. پیام ممکن است به‌دلیل پایان TTL، نامعتبرشدن اشتراک یا محدودیت مسیر انتقال دیگر قابل‌تحویل نباشد. بازکردن سایت فقط می‌تواند اجرای دوباره‌ی کد و ثبت اشتراک جدید را ممکن کند.

آیا پاک‌کردن داده‌های مرورگر راه‌حل مناسبی است؟

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

برای پشتیبانی چه اطلاعاتی ارسال کنیم؟

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