مشکل ارسال پوش نوتیفیکیشن؛ از کجا بفهمیم پیام در کدام مرحله گم شده است؟

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

بروزرسانی: زمان مطالعه حدود ۱۰ دقیقه نوشته‌ی تیم فنی فینگت

مشکل ارسال پوش نوتیفیکیشن را از کدام سمت شروع کنیم؟

اولین سؤال در هر مشکل ارسال پوش نوتیفیکیشن این است: «شکست در کدام قطعه‌ی زنجیر رخ داده؟» زنجیر سه حلقه دارد. حلقه‌ی اول سرور شماست؛ شرط ارسال، ساخت پیام و فراخوانی API. حلقه‌ی دوم سرویس پوش است که پیام را می‌پذیرد یا با کد خطا رد می‌کند. حلقه‌ی سوم دستگاه کاربر است که اجازه دارد پیام را نشان ندهد.

جمله‌ی «پوش ارسال نمی‌شود» در عمل چند معنی متفاوت دارد: یا درخواست به سرویس پوش نرسیده، یا سرویس آن را رد کرده، یا پذیرفته ولی گوشی نمایش نداده است. بیشتر تیم‌ها وقتشان را روی حلقه‌ی اشتباه تلف می‌کنند، مثلاً کد سرور را ساعت‌ها زیر و رو می‌کنند در حالی که کاربر اعلان اپ را در تنظیمات خاموش کرده بود.

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

مسیر عیب‌یابی پنج‌مرحله‌ای وقتی پوش نمی‌رسد

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

  1. یک پیام آزمایشی ساده بفرستید

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

  2. پاسخ سرویس پوش را لاگ کنید

    هر ارسال باید یک پاسخ داشته باشد: موفق یا کد خطا. اگر پاسخ را نمی‌خوانید، عملاً کور هستید.

  3. توکن یا اشتراک را بسنجید

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

  4. وضعیت اعلان روی خود دستگاه را ببینید

    مجوز اعلان، کانال اعلان در اندروید، حالت مزاحم نشوید و محدودیت باتری یکی‌یکی چک شوند.

  5. شبکه را بررسی کنید

    آیا دستگاه به اینترنت وصل است؟ آیا سرور شما به سرویس پوش دسترسی دارد؟ فایروال یا فیلتر روی خروجی سرور هم یک دلیل شناخته‌شده است.

علت‌های سمت سرور شما؛ پیام اصلاً ساخته یا فرستاده نشده

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

توکن‌های باطل در پایگاه‌داده

پس از هر پاک و نصب دوباره‌ی اپ توکن عوض می‌شود. اگر سرور توکن جدید را نگیرد، پیام به آدرس قدیمی می‌رود و سرویس پوش «توکن نامعتبر» برمی‌گرداند.

اعتبارنامه‌ی منقضی یا اشتباه

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

خطای پیش‌شرط در کد

شرط‌های «کاربر فعال است؟» یا «ساعت مجاز است؟» بی‌صدا پیام را حذف می‌کنند و هیچ لاگی نمی‌ماند.

صف یا کارگر پس‌زمینه‌ی متوقف

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

فراتر رفتن از حجم مجاز

متن یا داده‌ی پیام از سقف چند کیلوبایتی سرویس‌های پوش بزرگ‌تر است و رد می‌شود.

اولویت یا TTL نامناسب

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

محدودیت دسترسی خروجی سرور

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

خواندن پاسخ سرویس پوش و حذف توکن نامعتبر؛ کد نمونه

برای اشتراک‌های وب پوش، کتابخانه‌ی web-push در Node.js پاسخ سرویس مرورگر را می‌دهد. وقتی کاربر اعلان را برای سایت شما از مرورگر پس بگیرد یا اشتراک منقضی شود، سرویس پوش کد ۴۰۴ یا ۴۱۰ برمی‌گرداند. این یعنی آن اشتراک دیگر وجود ندارد و باید از پایگاه‌داده حذف شود، نه این‌که هر بار دوباره تلاش کنید.

نمونه‌ی زیر هر اشتراک را جداگانه می‌فرستد و در صورت خطای ۴۰۴ یا ۴۱۰ اشتراک را برای حذف علامت می‌زند. نتیجه‌ی هر ارسال را برمی‌گرداند تا بتوانید آمار رسیدن به سرویس پوش را در لاگ ببینید. کلیدهای VAPID را یک بار با دستور npx web-push generate-vapid-keys بسازید و در متغیر محیطی نگه دارید.

send-push.mjs؛ ارسال و تشخیص اشتراک باطل
// npm install web-push
import webpush from 'web-push'

webpush.setVapidDetails(
  'mailto:admin@example.com',
  process.env.VAPID_PUBLIC,
  process.env.VAPID_PRIVATE,
)

// subs: آرایه‌ای از { id, subscription } که از پایگاه‌داده می‌آید
export async function sendToAll(subs, title, body) {
  const payload = JSON.stringify({ title, body })
  const report = { ok: 0, gone: [], failed: [] }

  for (const { id, subscription } of subs) {
    try {
      await webpush.sendNotification(subscription, payload, { TTL: 3600 })
      report.ok++
    } catch (err) {
      if (err.statusCode === 404 || err.statusCode === 410) {
        report.gone.push(id) // اشتراک دیگر وجود ندارد؛ از پایگاه‌داده حذف شود
      } else {
        report.failed.push({ id, status: err.statusCode, message: err.body || err.message })
      }
    }
  }
  console.log(report.ok + ' ok, ' + report.gone.length + ' gone, ' + report.failed.length + ' failed')
  return report
}

همین منطق برای پوش اپلیکیشن هم صادق است؛ فقط کدهای خطا فرق می‌کنند. در FCM مثلاً خطای «توکن ثبت‌نشده» همان معنی ۴۱۰ را دارد. اگر می‌خواهید معماری کامل آن را ببینید، Firebase Cloud Messaging چیست را بخوانید.

کدهای وضعیت و خطاهایی که زیاد می‌بینید

این فهرست برای وب پوش و سرویس‌های مشابه است؛ کدهای دقیق هر سرویس را در مستندات همان سرویس بخوانید.

۲۰۱
سرویس پوش درخواست را پذیرفت. این یعنی پیام در صف است، نه این‌که دیده شده یا حتی به دستگاه رسیده.
۴۰۰
قالب درخواست یا داده‌ی پیام ایراد دارد؛ معمولاً کلید یا بدنه‌ی اشتباه.
۴۰۱ و ۴۰۳
هویت فرستنده تأیید نشد. کلیدهای VAPID یا اعتبارنامه را بررسی کنید.
۴۰۴ و خطای ۴۱۰
اشتراک یا توکن دیگر وجود ندارد. سطر مربوط را حذف کنید.
۴۱۳
حجم پیام از سقف مجاز بیشتر است. محتوا را کوتاه کنید و جزئیات را در صفحه‌ی مقصد بگذارید.
۴۲۹
تعداد درخواست از سهمیه گذشته؛ ارسال را کند کنید و به پیام Retry-After توجه کنید.
۵۰۰ تا ۵۰۳
خطای موقت سرویس پوش. با فاصله‌ی فزاینده دوباره تلاش کنید.

علت‌های سمت گوشی؛ پیام رسیده ولی کاربر نمی‌بیند

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

تنظیمات اعلان اپ یا سایت

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

مزاحم نشوید و حالت تمرکز

در این حالت‌ها اعلان بی‌صدا در فهرست می‌نشیند یا اصلاً بالا نمی‌آید. پیام نرسیده نیست؛ دیده نشده است. برای اپ‌های حساس، اجازه‌ی عبور از این حالت فقط برای دسته‌ی اولویت‌دار (مثل زنگ تماس) وجود دارد، نه برای پیام عادی.

صرفه‌جویی باتری و محدودیت سازنده

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

نبود سرویس‌های لازم یا اتصال به آن‌ها

پوش اپلیکیشن روی اندروید معمولاً از سرویس‌های گوگل رد می‌شود. گوشی بدون این سرویس یا شبکه‌ای که دسترسی را محدود می‌کند، پیام را نمی‌گیرد. در این وضعیت مشکل نه در کد شماست نه در تنظیمات کاربر.

جدول عیب‌یابی سریع؛ علامت، علت محتمل و اقدام

علامتعلت محتملاقدام اول
برای همه‌ی کاربران نمی‌رسدکلید ارسال، شبکه‌ی سرور یا باگ در ارسالپیام آزمایشی ساده و بررسی پاسخ سرویس پوش
فقط برای بعضی کاربران نمی‌رسدتوکن باطل، مجوز خاموش، باتریسن توکن را ببینید و از کاربر بخواهید مجوز را بررسی کند
با تأخیر می‌رسدDoze، TTL بلند، اولویت پاییناولویت را فقط برای پیام فوری بالا ببرید
در پیش‌زمینه می‌رسد، پس‌زمینه نهساختار پیام یا مدیریت در اپنوع پیام (اعلان یا داده) را بازبینی کنید
پیام تکراری می‌رسدارسال مجدد بدون شناسه‌ی یکتابرای هر رویداد یک شناسه بگذارید و تکرار را حذف کنید
روی آیفون وب پوش نمی‌رسدسایت به صفحه‌ی اصلی اضافه نشدهدر پوش اپ و پوش وب شرایط را ببینید

سناریوی نمونه: مشکل ارسال پوش نوتیفیکیشن در یک فروشگاه

نمونه‌ی زیر فرضی است و فقط ترتیب فکر کردن را نشان می‌دهد.

سناریوی نمونه

نمونه: شکایت «خبری از ارسال سفارش نشد»

فروشگاهی چند مشتری دارد که می‌گویند اعلان ارسال سفارش را نگرفته‌اند. مدیر سایت اول به سراغ کد می‌رود و چیزی نمی‌یابد. با لاگ پاسخ سرویس پوش معلوم می‌شود حدود یک‌سوم درخواست‌ها با «توکن نامعتبر» برمی‌گردند؛ این توکن‌ها مال مشتریانی است که اپ را دوباره نصب کرده‌اند و اپ توکن تازه را به سرور نفرستاده بود.

سناریوی نمونه

نمونه: اصلاح

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

سناریوی نمونه

درس نمونه

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

اگر همین اعلان‌ها را با فینگت می‌فرستید

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

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

چک‌لیست پیشگیری؛ چطور مشکل ارسال پوش را کم کنیم

این عادت‌ها بیشتر مشکل‌ها را پیش از آن‌که شکایت شوند حل می‌کنند:

  • لاگ پاسخ هر ارسال حتی اگر موفق است. بدون لاگ نمی‌توانید بعداً علت را پیدا کنید.
  • حذف خودکار توکن‌های مرده هر پاسخ «ثبت‌نشده» یا ۴۱۰ باید سطر را پاک کند.
  • ثبت زمان آخرین دریافت توکن توکن‌هایی که ماه‌ها تازه نشده‌اند مشکوک‌اند.
  • صفحه‌ی «اعلان‌ها کار نمی‌کند؟» در اپ یا سایت چند گام ساده برای کاربر: مجوز، باتری، مزاحم نشوید.
  • پیام آزمایشی در تنظیمات دکمه‌ای که کاربر با آن همان لحظه یک اعلان آزمایشی بگیرد.
  • کانال یا مسیر پشتیبان برای پیام حیاتی مثلاً نمایش همان پیام داخل اپ یا ایمیل برای رویدادهایی که اهمیت دارند.
  • محدودیت تعداد پیام کاربری که زیاد اعلان می‌گیرد آن را خاموش می‌کند؛ این هم یک شکل «نرسیدن» است.

پرسش‌های متداول درباره مشکل ارسال پوش نوتیفیکیشن

چرا پوش نوتیفیکیشن ارسال نمی‌شود با این‌که سرور خطا نمی‌دهد؟

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

خطای ۴۱۰ در وب پوش یعنی چه؟

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

اعلان فقط وقتی اپ باز است می‌رسد، چرا؟

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

چطور بفهمم مشکل از سرور من است یا گوشی کاربر؟

یک پیام ساده‌ی آزمایشی به گوشی خودتان بفرستید. اگر رسید، سرور و مسیر سالم است و مشکل در توکن یا تنظیمات آن کاربر است. اگر نرسید، اول لاگ پاسخ سرویس پوش را ببینید.

توکن چند وقت یک بار عوض می‌شود؟

زمان ثابتی وجود ندارد. با پاک شدن داده‌ی اپ، نصب دوباره یا تصمیم سرویس پوش عوض می‌شود. بنابراین باید هر بار رویداد تازه‌شدن توکن را بگیرید و به سرور بفرستید.

آیا فینگت هم ممکن است اعلان را نشان ندهد؟

بله، اعلان فینگت هم تابع تنظیمات اندروید است. اگر کاربر اعلان اپ را خاموش کرده یا باتری را محدود کرده باشد، ممکن است پیام دیر برسد یا دیده نشود. پس برای پیام حیاتی یک راه پشتیبان نگه دارید.