بومرنگ پوشفا چیست؟ وب‌هوک گزارش تحویل و جلوگیری از ارسال تکراری
پاسخ کوتاه: بومرنگ پوشفا برای دریافت گزارش وضعیت تحویل پوش در وب‌هوک کاربرد دارد؛ اما «گزارش‌نشدن» مساوی «دریافت‌نشدن» نیست. برای استفاده ایمن، گیرنده باید احراز هویت شود، پاسخ‌گویی آن زمان‌بندی مشخصی داشته باشد و پردازش گزارش‌ها با کلید یکتا انجام شود تا یک گزارش یا timeout باعث ارسال دوباره و آزار کاربر نشود.
در این مقاله:
- بومرنگ چه مسئله‌ای را حل می‌کند؟
- گزارش تحویل دقیقاً چه معنایی دارد؟
- گیرنده وب‌هوک را چگونه ایمن کنیم؟
- timeout و گزارش دیررس را مدیریت کنید
- چطور از ارسال تکراری جلوگیری کنیم؟
- fallback را فقط با رضایت و ضرورت اجرا کنید
- چک‌لیست راه‌اندازی و آزمون
- پرسش‌های متداول
این قابلیت را بهتر است بخشی از سامانه پیگیری خود بدانید، نه تضمین تحویل صددرصدی. پوشفا از FCM برای ارسال استفاده می‌کند و وضعیت‌های ارسال و کلیک را گزارش می‌دهد؛ این وضعیت‌ها به شما داده عملیاتی می‌دهند، ولی نه اثبات می‌کنند انسان اعلان را خوانده و نه می‌توانند تمام علت‌های دیده‌نشدن پیام را از بین ببرند. برای زمینه فنی مشکلات دریافت، دلایل دریافت‌نشدن وب‌پوش را نیز ببینید.
بومرنگ چه مسئله‌ای را حل می‌کند؟
در این سناریو، شما هنگام ارسال پیام، دریافت گزارش تحویل را فعال و نشانی وب‌هوک سامانه خود را ثبت می‌کنید. پس از تغییر وضعیت، بومرنگ گزارشی را به آن نشانی می‌فرستد تا backend شما بتواند آن را ثبت کند، وضعیت سفارش یا کمپین را به‌روزرسانی کند و در صورت وجود قاعده مشخص، اقدام بعدی را بررسی کند.
اقدام بعدی نباید به‌صورت پیش‌فرض «ارسال مجدد» باشد. برای نمونه، اگر پیام مربوط به تغییر وضعیت سفارش است، می‌توانید ابتدا صفحه سفارش را در حساب کاربر به‌روزرسانی کنید. اگر پیام حساس به زمان است، شاید تماس با کاربر در کانال دیگری مناسب باشد؛ اما فقط پس از داشتن رضایت، مبنای ارتباط و قاعده‌ای روشن برای همان نوع پیام.
- گزارش‌گیری: رویدادها و زمان دریافت گزارش را در سامانه خود ذخیره کنید.
- واکنش کنترل‌شده: فقط برای سناریوهایی که ارزش و ضرورت آن مشخص است، اقدام جایگزین تعریف کنید.
- ردیابی: هر ارسال را به یک شناسه داخلی کمپین، کاربر و هدف کسب‌وکار وصل کنید.
- کاهش ریسک: با انقضا، سقف دفعات و جلوگیری از تکرار، تجربه کاربر را حفظ کنید.
گزارش تحویل دقیقاً چه معنایی دارد؟
در وب‌پوش، رسیدن پیام به مرحله نمایش اعلان با خوانده‌شدن آن تفاوت دارد. در این زنجیره، پذیرش ارسال، تحویل در مسیر، اجرای سرویس‌ورکر و نمایش اعلان مراحل متفاوتی هستند. یک acknowledgement یا تأیید تحویل را باید نشانه‌ای فنی از موفقیت مرحله مربوط بدانید، نه مدرک مشاهده یا کلیک انسان.
همچنین نبود acknowledgement دلیل قطعی برای نرسیدن نیست. ممکن است گیرنده وب‌هوک در دسترس نباشد، شبکه تأخیر داشته باشد، گزارش با تأخیر برسد یا وضعیت نهایی هنوز مشخص نشده باشد. بنابراین در طراحی خود، وضعیت «نامشخص» را از «شکست قطعی» جدا کنید.
برای پیام‌های آفلاین نیز زمان نگه‌داری اهمیت دارد. TTL یا مدت اعتبار فقط مشخص می‌کند پیام تا چه زمانی برای تحویل تلاش شود؛ این مفهوم، ذخیره‌سازی نامحدود یا تضمین تحویل پس از اتصال دوباره نیست. توضیح فنی FCM درباره این تفاوت در مستندات طول عمر پیام آمده است.
| وضعیت داخلی پیشنهادی | برداشت مناسب | اقدام ایمن |
|---|---|---|
| ثبت‌شده | ارسال در سامانه شما ایجاد شده | انتظار گزارش و نگه‌داشتن شناسه داخلی |
| تحویل گزارش‌شده | مرحله فنی تحویل یا نمایش موفق گزارش شده | عدم ارسال دوباره؛ در صورت نیاز، انتظار کلیک جداگانه |
| در انتظار | هنوز نتیجه قابل اتکا نداریم | صبر تا timeout و بررسی گزارش دیررس |
| ناموفق | گزارش شکست معتبر دریافت شده | بررسی علت و اجرای قاعده مجاز، نه تکرار خودکار همیشگی |
| منقضی | پنجره زمانی پیام تمام شده | عدم ارسال همان پیام بعد از انقضا |
گیرنده وب‌هوک را چگونه ایمن کنیم؟
وب‌هوک یک ورودی عمومی از اینترنت است و نباید مانند یک endpoint بدون محافظت ساخته شود. دست‌کم یک مسیر اختصاصی برای دریافت گزارش ایجاد کنید و احراز هویت را در لایه‌ای انجام دهید که فقط سرویس مجاز بتواند درخواست معتبر تولید کند. روش دقیق امضای درخواست یا توکن را فقط مطابق امکانات واقعی پنل و مستندات سرویس پیاده کنید؛ الگوریتم یا نام فیلدی را که در اختیار ندارید حدس نزنید.
- نشانی وب‌هوک را روی HTTPS قرار دهید.
- توکن یا اعتبارنامه را در سرور نگه‌داری و دوره‌ای تعویض کنید؛ آن را در مرورگر یا اپلیکیشن موبایل قرار ندهید.
- محدودسازی نرخ، ثبت IP و ثبت زمان دریافت را در نظر بگیرید.
- بدنه درخواست و اندازه آن را اعتبارسنجی کنید و داده‌های اضافی را نادیده بگیرید.
- در لاگ‌ها اطلاعات شخصی و محتوای حساس پیام را بی‌دلیل ذخیره نکنید.
اگر برای تأیید اصالت گزارش، روش مستندی در اتصال فعلی ندارید، وجود یک لایه واسط به‌تنهایی این مشکل را حل نمی‌کند. گزارش را بدون تطبیق با اطلاعات معتبر سروری، مبنای اقدام حساس نگذارید. پیش از طراحی امضا یا توکن، امکانات واقعی فرستنده و گیرنده را بررسی کنید؛ بررسی ساختار JSON یا نشانی IP، معادل تأیید رمزنگاری‌شده اصالت درخواست نیست.
timeout و گزارش دیررس را مدیریت کنید
برای وب‌هوک، timeout را کوتاه اما واقع‌بینانه تعیین کنید. گیرنده باید پس از اعتبارسنجی اولیه و ثبت رویداد، سریع پاسخ دهد و پردازش‌های سنگین مانند ارسال ایمیل یا بررسی سفارش را به صف داخلی بسپارد. اگر endpoint برای مدت طولانی منتظر سرویس دیگری بماند، ممکن است یک رویداد معتبر به‌اشتباه شکست‌خورده تلقی شود.
در backend، این سه زمان را جداگانه نگه دارید: زمان ایجاد ارسال، زمان دریافت گزارش و زمان تصمیم‌گیری برای اقدام بعدی. اگر timeout رخ داد، وضعیت را موقتاً «نامشخص» بگذارید و یک پنجره انتظار برای گزارش دیررس داشته باشید. پس از پایان آن پنجره، فقط در صورتی به وضعیت شکست بروید که سیاست کسب‌وکار و شواهد فنی چنین تصمیمی را توجیه کند.
- درخواست را دریافت کنید.
- احراز هویت و ساختار رویداد را بررسی کنید.
- رویداد را با کلید یکتا ثبت کنید.
- پاسخ سریع به فرستنده بدهید.
- پردازش تصمیم را در صف یا worker انجام دهید.
- گزارش‌های دیررس را با وضعیت قبلی تطبیق دهید، نه اینکه رویداد تازه‌ای بسازید.
چطور از ارسال تکراری جلوگیری کنیم؟
در اینجا idempotency یا «پردازش بدون اثر جانبی تکراری» یعنی یک رویداد تکراری، نتیجه جانبی جدید ایجاد نکند. برای هر ارسال، یک شناسه داخلی یکتا بسازید و ترکیب شناسه ارسال، نوع رویداد و اقدام را در پایگاه داده با محدودیت یکتا ذخیره کنید. اگر همان گزارش دوباره رسید، پاسخ موفق بدهید اما اقدام قبلی را دوباره اجرا نکنید.
این کنترل برای retry شبکه، timeout و پردازش هم‌زمان ضروری است. قفل کوتاه‌مدت یا تراکنش پایگاه داده از این وضعیت جلوگیری می‌کند که دو worker هم‌زمان برای یک کاربر پیام جایگزین بفرستند. همچنین تاریخ انقضا و سقف اقدام داشته باشید؛ مثلاً یک پیام سفارش که دو ساعت از زمان اعتبارش گذشته، نباید صرفاً به دلیل دریافت گزارش دیررس دوباره ارسال شود.
قابلیت collapse_id در برخی مسیرهای API می‌تواند برای پیام‌های قابل جایگزینی مفید باشد، اما رفتار collapse در پلتفرم‌ها یکسان نیست و با جایگزین‌شدن اعلان نمایش‌داده‌شده تفاوت دارد. بنابراین آن را تنها بخشی از راهکار بدانید، نه جایگزین idempotency در backend. درباره این موضوع می‌توانید راهنمای Collapse ID را بخوانید.
fallback را فقط با رضایت و ضرورت اجرا کنید
fallback یعنی مسیر جایگزین پس از نامشخص‌ماندن یا شکست یک کانال؛ برای مثال، پیشنهاد مراجعه به صندوق پیام داخل حساب کاربر یا ارسال ایمیل برای کاربری که قبلاً رضایت داده است. این تصمیم باید بر اساس نوع پیام، فوریت، ترجیح کاربر و انقضای محتوا گرفته شود. تبدیل خودکار هر گزارش نامشخص به پیامک یا ایمیل هم از نظر تجربه کاربر پرریسک است و هم می‌تواند با رضایت ثبت‌شده سازگار نباشد.
برای هر fallback یک جدول تصمیم بسازید: چه رویدادی آن را فعال می‌کند، حداکثر چند بار مجاز است، در چه بازه‌ای معتبر است و چگونه لغو یا ثبت می‌شود. برای پیام تبلیغاتی، نبود کلیک را شکست تحویل فرض نکنید و کانال دیگری را خودکار فعال نکنید. برای پیام تراکنشی، صفحه امن حساب کاربر می‌تواند مسیر جایگزین کم‌خطر‌تری از ارسال محتوای حساس در URL باشد.
چک‌لیست راه‌اندازی و آزمون
- یک endpoint جداگانه برای وب‌هوک ساخته‌اید و HTTPS فعال است.
- روش احراز هویت و سیاست نگه‌داری رازها مشخص است.
- دریافت، ثبت و پاسخ سریع از پردازش اقدام بعدی جدا شده‌اند.
- وضعیت‌های «در انتظار»، «تحویل گزارش‌شده»، «ناموفق» و «منقضی» از هم تفکیک شده‌اند.
- برای رویداد تکراری، اقدام جانبی دوباره اجرا نمی‌شود.
- گزارش دیررس، timeout قبلی را بدون بررسی به ارسال مجدد تبدیل نمی‌کند.
- برای هر پیام، زمان اعتبار و سقف دفعات اقدام تعیین شده است.
- fallback فقط برای کاربران واجد شرایط و با رضایت معتبر فعال می‌شود.
- آزمایش با وب‌هوک در دسترس، پاسخ کند، پاسخ تکراری و گزارش دیررس انجام شده است.
- لاگ‌ها برای عیب‌یابی کافی‌اند اما رازها و داده‌های حساس را افشا نمی‌کنند.
برای آزمون عملی، ابتدا یک پیام کم‌اهمیت برای کاربر آزمایشی بفرستید. سپس در محیط کنترل‌شده، پاسخ endpoint را عمداً با تأخیر مواجه کنید، همان رویداد را دوباره بفرستید و یک گزارش دیررس بسازید. معیار موفقیت این نیست که هیچ رخدادی تکرار نشود؛ معیار این است که ثبت رویداد و اقدام جانبی، با وجود تکرار و تأخیر، فقط یک‌بار انجام شود.
پرسش‌های متداول
آیا نبود گزارش وب‌هوک یعنی کاربر پیام را نگرفته است؟
خیر. نبود گزارش می‌تواند ناشی از تأخیر شبکه، در دسترس‌نبودن گیرنده یا نامشخص‌بودن وضعیت باشد. آن را ابتدا «نامشخص» ثبت کنید، نه شکست قطعی.
آیا گزارش تحویل یعنی کاربر اعلان را خوانده است؟
خیر. acknowledgement معمولاً به موفقیت مرحله فنی نمایش اعلان مربوط است و اثباتی برای خواندن، توجه یا کلیک کاربر نیست.
آیا می‌توانم پس از هر گزارش ناموفق پیامک بفرستم؟
فقط اگر کاربر برای آن کانال رضایت داده، پیام هنوز معتبر و ضروری است و سیاست شما سقف دفعات و انقضا دارد. در غیر این صورت، fallback خودکار می‌تواند به ارسال مزاحم یا تکراری منجر شود.