نحوه دریافت و ذخیره توکن های Subscriber ID و توکن FCM برای یک مخاطب خاص

راهنمای دریافت توکن FCM و Subscriber ID و ذخیره شناسه مخاطب در بک‌اند پس از پذیرش پوش، با نمونه‌های آماده و سفارشی.

راهنمای ذخیره مشترکانی که مجوز دریافت پوش داده‌اند

شناسه ثابت مخاطب (Subscriber ID) چیست؟ (پیشنهادی)

پوشفا برای هر بازدیدکننده سایتتان شناسه‌ای با نام Subscriber ID صادر می‌کند. بازدیدکننده ممکن است این شناسه را داشته باشد و هنوز عضو پوش نشده باشد. برای ارسال پوش نوتیفیکیشن به مخاطبی که اشتراک پوش فعال دارد، بهتر است از همین شناسه استفاده کنید. این شناسه با تغییر توکن FCM عوض نمی‌شود.

متد Pushfa.getSubscriberId() پس از آماده شدن پروفایل، شناسه بازدیدکننده جاری سایتتان را برمی‌گرداند، حتی اگر کاربر هنوز مجوز دریافت پوش نداده باشد. پس دریافت subscriber_id به‌تنهایی به معنی فعال بودن اشتراک پوش نیست. اگر مشترک شناسه داشته باشد اما هنوز توکن پوش نداشته باشد، وب‌سرویس او را با کد PUSH_NOT_SUBSCRIBED رد می‌کند. وضعیت HTTP متناظر با این کد 422 است.

پیش از استفاده از نمونه کد

پس از نصب سرویس‌ورکر طبق راهنمای پوشفا، یکی از دو نمونه زیر را متناسب با نوع کادر عضویت انتخاب کنید و کد آن را پیش از تگ SDK قرار دهید. اگر تگ SDK را قبلاً اضافه کرده‌اید، از افزودن مجدد آن خودداری کنید. به‌جای YOUR_PUBLIC_KEY کلید عمومی سرویس خود و به‌جای /api/push-subscribers آدرس وب‌سرویسی را بگذارید که برای ذخیره شناسه در بک‌اند سایتتان پیاده‌سازی کرده‌اید.

حالت اول: دریافت Subscriber ID در حالت استفاده از سافت پرامپت آماده پوشفا

برای ذخیره شناسه مشترکانی که مجوز دریافت پوش داده‌اند، به رویداد pushfaTokenChange گوش دهید. این رویداد پس از دریافت مجوز از کاربر و ثبت موفق توکن در پوشفا اجرا می‌شود. داخل رویداد، متد Pushfa.getSubscriberId() را صدا بزنید و مقدار subscriber_id را برای ذخیره‌سازی به بک‌اند سایتتان بفرستید. با این روش، فقط شناسه بازدیدکنندگانی را برای ارسال پوش ذخیره می‌کنید که دست‌کم یک‌بار مجوز دریافت پوش داده‌اند.

این نمونه برای کادر آماده عضویت پوشفا، مانند OneSignal یا Bottom sheet است. نمایش خودکار کادر به‌صورت پیش‌فرض فعال است. اگر قبلاً آن را خاموش کرده‌اید، تنظیم autoPrompt: false یا manual_prompt=1 را بردارید. شنونده رویداد را پیش از بارگذاری SDK ثبت کنید.
<script>
async function savePushfaSubscriber(token) {
  if (!token || !('Notification' in window) || Notification.permission !== 'granted') return;

  const subscriberId = window.Pushfa.getSubscriberId();
  if (!subscriberId) return;

  const response = await fetch('/api/push-subscribers', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ subscriber_id: subscriberId }),
  });
  if (!response.ok) throw new Error('ذخیره شناسه در سایت شما انجام نشد.');
}

// مشترک جدید یا تغییر توکن: پس از ثبت موفق توکن در پوشفا
window.addEventListener('pushfaTokenChange', (event) => {
  savePushfaSubscriber(event.detail).catch(console.error);
});
</script>

<script
  src="https://sdk.pushfa.com/notification-v2.js?api_public_key=YOUR_PUBLIC_KEY"
  type="module">
</script>

حالت دوم: دریافت Subscriber ID در حالت استفاده از دکمه دستی یا پرامپت کاستوم سایت

اگر دکمه یا کادر عضویت را خودتان می‌سازید، پس از کلیک کاربر متد Pushfa.requestPermission() را صدا بزنید و منتظر نتیجه بمانید. پس از تأیید مجوز مرورگر و ثبت موفق توکن، با Pushfa.getSubscriberId() شناسه را بگیرید و به همان وب‌سرویس بک‌اند سایتتان بفرستید. اگر کاربر مجوز ندهد یا ثبت توکن موفق نباشد، نمونه زیر شناسه‌ای به بک‌اند نمی‌فرستد.

دکمه enable-push متعلق به این نمونه است و پس از بارگذاری SDK فعال می‌شود. اگر دکمه خودتان را دارید، کد کلیک را به همان دکمه وصل کنید و enable-push را با شناسه دکمه خود جایگزین کنید. اگر زمان نمایش کادر را خودتان کنترل می‌کنید، autoPrompt: false را نگه دارید. اگر از custom_soft_prompt و رویداد pushfaCustomPromptRequest برای نمایش کادر استفاده می‌کنید، تنظیم autoPrompt: false را بردارید.
<button id="enable-push" type="button" disabled>فعال‌سازی اعلان‌ها</button>
<p id="push-status" role="status"></p>

<script>
window.PushfaConfig = { ...window.PushfaConfig, autoPrompt: false };

document.getElementById('enable-push').addEventListener('click', async (event) => {
  const button = event.currentTarget;
  const status = document.getElementById('push-status');
  button.disabled = true;
  status.textContent = 'لطفاً اجازه اعلان را در مرورگر تأیید کنید.';

  try {
    const token = await window.Pushfa.requestPermission();
    if (!token || !('Notification' in window) || Notification.permission !== 'granted') {
      status.textContent = 'اعلان فعال نشد؛ هیچ شناسه‌ای به سایت شما ارسال نشد.';
      return;
    }

    const subscriberId = window.Pushfa.getSubscriberId();
    if (!subscriberId) {
      status.textContent = 'شناسه آماده نشد؛ دوباره تلاش کنید.';
      return;
    }

    const response = await fetch('/api/push-subscribers', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ subscriber_id: subscriberId }),
    });
    if (!response.ok) throw new Error('ذخیره شناسه در سایت شما انجام نشد.');
    status.textContent = 'اعلان فعال شد و شناسه در سایت شما ذخیره شد.';
  } catch (error) {
    status.textContent = error.message || 'خطایی رخ داد؛ دوباره تلاش کنید.';
  } finally {
    button.disabled = false;
  }
});
</script>

<script
  src="https://sdk.pushfa.com/notification-v2.js?api_public_key=YOUR_PUBLIC_KEY"
  type="module"
  onload="document.getElementById('enable-push').disabled = false">
</script>

ذخیره شناسه و وضعیت دریافت پوش در بک‌اند

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

شناسه جدید

مشترک را به‌عنوان دستگاه جدید ذخیره کنید و وضعیت دریافت پوش را فعال (push_active = true) قرار دهید.

شناسه موجود و غیرفعال

همان رکورد را دوباره فعال کنید (push_active = true) و خطای قبلی را پاک کنید.

شناسه موجود و فعال

نیازی به درج دوباره یا تغییر وضعیت نیست.

برای جلوگیری از ثبت رکورد تکراری، ترکیب سرویس و subscriber_id را یکتا کنید. push_active نام پیشنهادی فیلد دیتابیس شماست. هنگام دریافت شناسه، احراز هویت و CSRF را مطابق سایت خود اعمال کنید. برای تأیید اشتراک از سرور پوشفا، هر دو مقدار exists = true و has_push = true را بررسی کنید. کلید خصوصی پوشفا فقط در بک‌اند بماند.
فیلد پیشنهادیچه چیزی نگه می‌دارد؟نحوه استفاده
service_id + subscriber_id سرویس و شناسه پایدار همان دستگاه؛ ترکیب یکتا تمام جست‌وجوها و تغییر وضعیت‌ها را به همین سرویس محدود کنید.
user_id کاربر سایت شما، در صورت ورود به حساب هویت کاربر را از Session یا توکن معتبر سایت خود تعیین کنید.
push_active آخرین وضعیت شناخته‌شده قابلیت ارسال پوش: true یا false پس از ثبت موفق اشتراک true؛ پس از خطای مشخصِ اشتراک false.
last_push_error_code آخرین علت توقف ارسال، در صورت وجود برای عیب‌یابی ذخیره کنید؛ هنگام فعال‌سازی مجدد پاک کنید.

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

ارسال را فقط به شناسه‌هایی محدود کنید که وضعیت دریافت پوش آن‌ها در دیتابیس فعال است. برای ارسال تکی، در وب‌سرویس ارسال تکی subscriber_id را بفرستید. در وب‌سرویس send-via-subscriber-id، شناسه یک یا چند مخاطب را در آرایه subscriber_ids بفرستید. پس از ارسال، اگر برای شناسه‌ای یکی از کدهای جدول زیر را از وب‌سرویس پوشفا دریافت کردید، وضعیت دریافت پوش همان شناسه را در دیتابیس به غیرفعال (push_active = false) تغییر دهید تا ارسال‌های بعدی به آن متوقف شود.

ملاک تصمیم error_code است. در ارسال تکی کد خطا را از پاسخ بخوانید. در send-via-subscriber-id، کد مربوط به هر شناسه ردشده را در data.rejected_recipients بررسی کنید. حتی در پاسخ HTTP 200 ممکن است برخی شناسه‌ها رد شده باشند. خطاهایی مانند VALIDATION_ERROR و LAST_VISIT_CONDITION_NOT_MET وضعیت دریافت پوش را تغییر نمی‌دهند.
HTTP Codeerror_codeمعنی
404 SUBSCRIBER_NOT_FOUND شناسه در این سرویس پیدا نشد. ممکن است پس از ۹۰ روز غیرفعال ماندن توکن، پروفایل حذف شده باشد.
410 PUSH_TOKEN_EXPIRED توکن فعلی نامعتبر است. علت دقیق آن از پاسخ مشخص نیست.
422 PUSH_NOT_SUBSCRIBED پروفایل وجود دارد، اما توکن پوش ندارد.
{
  "error_code": "PUSH_TOKEN_EXPIRED",
  "message": "توکن Push این مشترک منقضی یا باطل شده است."
}
فیلدهای مهم پاسخ در نمونه خطای PUSH_TOKEN_EXPIRED

وقتی کاربر دوباره اجازه اعلان می‌دهد

اگر کاربر مجوز دریافت پوش را در مرورگر دوباره به حالت مجاز تغییر دهد، پس از بازگشت او به سایت و ثبت موفق توکن جدید یا جایگزین، رویداد pushfaTokenChange دوباره اجرا می‌شود. شناسه را مانند بار اول به بک‌اند بفرستید. اگر همان subscriber_id در دیتابیس غیرفعال است، آن را دوباره فعال کنید تا ارسال‌های بعدی برای مشترک از سر گرفته شود. در حالت دکمه سفارشی، پس از نتیجه موفق requestPermission() نیز همین مسیر را اجرا کنید.

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

دیاگرام دریافت، ذخیره و ارسال با شناسه مشترک

برای تصمیم درباره نتیجه ارسال، error_code همان شناسه را با جدول بالا مقایسه کنید. وضعیت HTTP در تصویر خلاصه شده است. پاسخ ۴۱۰ علت نامعتبر شدن توکن را مشخص نمی‌کند و پاسخ ۲۰۰ هم می‌تواند شامل شناسه‌های ردشده باشد.
روند نمایش کادر عضویت، دریافت مجوز، دریافت شناسه، ذخیره در بک‌اند و بررسی نتیجه ارسال
روند عضویت با سافت پرامپت آماده، ذخیره شناسه و بررسی نتیجه ارسال.

استعلام وضعیت شناسه‌های قبلی از سرور پوشفا

POST
https://pushfa.com/api/webservices/subscribers/state

برای تأیید وضعیت ثبت‌شده در پوشفا، این درخواست را فقط از بک‌اند خود و با کلید عمومی و خصوصی همان سرویس بفرستید. subscriber_ids در هر درخواست باید بین ۱ تا ۲۵ شناسه داشته باشد. نتیجه هر شناسه در data.subscribers برمی‌گردد. این استعلام، آخرین وضعیت شناخته‌شده سرور را نشان می‌دهد؛ اگر کاربر همین حالا مجوز مرورگر را تغییر داده و هنوز ثبت یا ارسال تازه‌ای انجام نشده باشد، ممکن است این تغییر هنوز به سرور نرسیده باشد.

خطای شبکه، timeout یا خطای احراز هویت به معنی غیرفعال‌بودن مشترک نیست؛ در این حالت وضعیت رکوردها را تغییر ندهید. کلید خصوصی را برای انجام استعلام به مرورگر نفرستید.
فیلدهای هر آیتم در data.subscribersمعنیاقدام
exists = true و has_push = true پروفایل در این سرویس هست و توکن پوش معتبر دارد. رکورد مربوط را فعال نگه دارید یا دوباره فعال کنید.
exists = true و has_push = false پروفایل هست، اما اکنون توکن معتبر و قابل ارسال ندارد. push_active = false؛ شناسه را برای فعال‌سازی مجدد نگه دارید.
exists = false این شناسه در سرویس موردنظر پیدا نشد. پس از بررسی سرویس، از فهرست ارسال خارج کنید.
{
  "api_public_key": "YOUR_PUBLIC_KEY",
  "api_private_key": "YOUR_PRIVATE_KEY",
  "subscriber_ids": ["f1444a41-b3af-4e30-8655-9a70de1e0915"]
}

توکن FCM چیست؟

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

دریافت و ذخیره توکن FCM (سازگاری قدیمی)

اگر اتصال قدیمی شما بر پایه توکن FCM است، همچنان می‌توانید با رویداد pushfaTokenChange توکن را دریافت و در سرور ذخیره کنید. برای پیاده‌سازی‌های جدید و ارسال پایدار، استفاده از Subscriber ID و کلید subscriber_id توصیه می‌شود.

window.addEventListener('pushfaTokenChange', (event) => {
  const token = event.detail;
  if (!token || !('Notification' in window) || Notification.permission !== 'granted') return;

  // برای سازگاری با اتصال قدیمی، توکن FCM را در سرور ذخیره کنید
  fetch('/api/save-token', {
    method: 'POST',
    body: JSON.stringify({ token }),
    headers: { 'Content-Type': 'application/json' },
  });
});

دریافت توکن و شناسه ثابت مخاطب (Subscriber ID) به‌صورت مستقیم

متد Pushfa.getSubscriberId() هویت پروفایل این مرورگر را برمی‌گرداند؛ این شناسه ممکن است پیش از پذیرش اعلان هم وجود داشته باشد. مقدار Pushfa.getToken() نیز توکن ذخیره‌شده مرورگر است و به‌تنهایی فعال‌بودن فعلی اشتراک را تضمین نمی‌کند. برای ذخیره مقصدهای قابل ارسال، از مسیر موفق ثبت اشتراک در نمونه‌های بالا استفاده کنید. اگر فقط می‌خواهید پروفایل را به حساب واردشده سایت خود متصل کنید، می‌توانید شناسه را جداگانه ذخیره کنید، اما صرف این اتصال نباید push_active را true کند. برای تأیید وضعیت ثبت‌شده در پوشفا، استعلام سمت سرور را به کار ببرید.

const token = window.Pushfa.getToken();
const subscriberId = window.Pushfa.getSubscriberId();
console.log({ token, subscriberId });

یک رویکرد نوین برای مدیریت توکن ها - استفاده از alias و custom alias

روش‌های قبلی با این هدف و رویکرد هستند که یکی از توکن‌های subscriber_id یا fcm_token مخاطب را به بک‌اند سایت شما برسانند، سپس آن را در دیتابیس ذخیره و هنگام ارسال استفاده کنید. اما می‌توان رویکرد معکوسی در پیش گرفت: به‌جای ذخیره و مدیریت توکن‌ها در دیتابیس خودتان و در نظر گرفتن یکی از توکن‌ها به‌عنوان مقصد، مدیریت توکن‌ها را کاملاً به پوشفا بسپارید؛ بدون اینکه با subscriber_id یا fcm_token درگیر شوید. هر زمان لازم بود، با فراخوانی متدهای alias یا در حالت گسترده‌تر custom_alias برای توکن‌های سمت پوشفا یک شناسه مستعار انتخاب کنید؛ برای مثال، آیدی کاربر در دیتابیس سیستم خود را به‌صورت Hash‌شده یا UUID (برای امنیت بیشتر) استفاده کنید. در این حالت، این شناسه به‌صورت خودکار به توکن جاری کاربر در پوشفا متصل می‌شود و هر زمان قصد ارسال پیام به کاربر موردنظر را داشتید، کافی است پیام را با ارائه شناسه مستعار در وب‌سرویس ارسال پیام از طریق alias یا custom_alias پوشفا ارسال کنید. به بیان دقیق‌تر، شناسه مستعار که شناسه‌ای در سیستم شماست به پوشفا ارائه می‌شود و پوشفا آن را به کاربر جاری متصل می‌کند؛ ارسال نیز با ارائه همین شناسه به‌عنوان مقصد انجام می‌شود. هر زمان تمایل داشته باشید می‌توانید این شناسه را حذف کنید؛ در این صورت توکن جاری در مرورگر کاربر دیگر به آن شناسه متصل نخواهد بود. اگر کاربر چند دستگاه (چند توکن) با یک شناسه داشته باشد، پیام به تمام دستگاه‌هایی که آن شناسه به آن‌ها متصل است ارسال می‌شود و هزینه آن به‌صورت گروهی کسر خواهد شد. برای اطلاعات بیشتر، مطالب زیر را مطالعه کنید.

Ctrl+I