مستندات پوشفا
Pro

Collapse ID — جایگزینی نوتیفیکیشن

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

Collapse ID چیست؟

Collapse ID یک رشته متنی دلخواه است که به نوتیفیکیشن اختصاص می‌دهید. اگر قبل از اینکه کاربر اعلان قبلی را ببندد، نوتیفیکیشن جدیدی با همان Collapse ID ارسال کنید، مرورگر (WebPush Topic header) و اندروید (FCM collapse_key) پیام قدیمی را با پیام جدید جایگزین می‌کنند — به جای اینکه هر دو را نشان دهند. این دقیقاً همان collapse_key در FCM و Topic در WebPush است که OneSignal هم از آن استفاده می‌کند.

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

کاربردهای رایج

Collapse ID برای محتواهایی مناسب است که سریع منسوخ می‌شوند:

سناریو نمونه Collapse ID توضیح
نتیجه زنده مسابقه live_score_123 هر به‌روزرسانی امتیاز، اعلان قبلی را جایگزین می‌کند
قیمت سهام / ارز stock_BTC آخرین قیمت جایگزین قیمت قدیمی می‌شود
وضعیت سفارش order_9090 از «ارسال شد» به «تحویل داده شد» با یک اعلان به‌روز می‌شود
اعلان آب‌وهوا weather_today پیش‌بینی به‌روز شده جایگزین می‌شود

استفاده از پنل

در فرم ارسال پوش نوتیفیکیشن (هم ارسال تکی و هم ارسال گروهی) بخش «تنظیمات پیشرفته» را باز کنید. فیلد «Collapse ID» را پیدا کنید و رشته موردنظر خود را وارد کنید. این مقدار به صورت خودکار هم به FCM (collapse_key در Android) و هم به WebPush (Topic header) اعمال می‌شود.

Collapse ID حداکثر ۱۰۰ کاراکتر می‌تواند داشته باشد. از کاراکترهای ASCII استفاده کنید.

پارامتر API

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

فیلد توضیح اجباری
collapse_id Collapse ID Pro Collapse ID — رشته متنی جایگزینی؛ اگر پیامی با همین شناسه در صف دستگاه باشد با پیام جدید جایگزین می‌شود خیر - فقط Pro
صفحه معرفی Collapse ID ارسال تکی کامل ارسال گروهی کامل

نمونه درخواست API

ارسال گروهی با Collapse ID — هر ارسال مجدد با همان collapse_id اعلان قبلی را در مرورگر کاربر جایگزین می‌کند:

curl -X POST https://pushfa.com/api/webservices/send-group-message \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "topic": "all",
    "title": "نتیجه زنده: استقلال ۲ — پرسپولیس ۱",
    "body": "دقیقه ۷۸",
    "collapse_id": "live_score_match_42",
    "sendTime": "current"
  }'

محدودیت‌های مرورگر

رفتار Collapse ID بسته به مرورگر متفاوت است:

اگر کاربر چند برگه از سایت شما باز داشته باشد و سرویس‌ورکر در همه آن‌ها فعال باشد، رفتار جایگزینی بسته به پیاده‌سازی مرورگر ممکن است کمی متفاوت باشد.
مرورگر وضعیت نکته
Chrome / Edge (Chromium) ✅ کامل FCM collapse_key + Topic header هر دو اعمال می‌شوند
Firefox ✅ کامل WebPush Topic header پشتیبانی می‌شود
Samsung Internet ✅ کامل از طریق FCM
Safari iOS 16.4+ ⚠️ محدود پشتیبانی از WebPush Topic در نسخه‌های جدیدتر