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

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

توکن FCM چیست؟

توکن FCM یک شناسه منحصربه‌فرد برای هر ترکیب مرورگر-دستگاه است که پوشفا برای ارسال اعلان پوش به آن دستگاه از آن استفاده می‌کند. این توکن ممکن است در طول زمان تغییر کند (مثلاً بعد از پاک شدن cache مرورگر). وجود Subscriber ID به‌تنهایی به معنی فعال بودن Push نیست. ابتدا اجازه اعلان و ثبت توکن باید موفق شود؛ سپس شناسه را ذخیره کنید. بر اساس نوع کادر درخواست، یکی از دو نمونه مستقل زیر را انتخاب کنید.

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

برخلاف توکن FCM که ممکن است در طی زمان به مرور تغییر کند، شناسه ثابت مخاطب (Subscriber ID) یک شناسه ثابت است که پوشفا به هر دستگاه (مرورگر) اختصاص می‌دهد و حتی پس از تجدید توکن FCM ثابت می‌ماند. وجود Subscriber ID به‌تنهایی به معنی فعال بودن Push نیست. ابتدا اجازه اعلان و ثبت توکن باید موفق شود؛ سپس شناسه را ذخیره کنید. بر اساس نوع کادر درخواست، یکی از دو نمونه مستقل زیر را انتخاب کنید.

در دریافت، ذخیره و ارسال، Subscriber ID به دلیل پایداری بیشتر توصیه می‌شود؛ برای یک مخاطب از subscriber_id و برای چند مخاطب از subscriber_ids[] استفاده کنید. توکن FCM ممکن است تغییر کند و کلیدهای fcm_token و fcm_tokens[] فقط برای سازگاری قدیمی پشتیبانی می‌شوند.

قبل از کپی کد این مطلب را بخوانید!

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

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

این حالت برای کسانی است که کادر آماده پوشفا مثل OneSignal یا Bottom sheet را انتخاب کرده‌اند. به بیان دقیق‌تر، نمایش خودکار پرامپت باید فعال باشد (که به شکل پیش‌فرض فعال است) و در صورت تغییر در تنظیمات پیش‌فرض پوشفا، باید تنظیمات autoPrompt: false یا manual_prompt=1 را بردارید. کل نمونه زیر را در صفحه بگذارید؛ قسمت گوش‌دادن به رویداد باید قبل از تگ SDK باشد. نیازی به دکمه جدید یا پیدا کردن دکمه داخلی پوشفا ندارید. برای مشترک جدید، ارسال شناسه پس از تأیید کادر و مجوز مرورگر و ثبت موفق توکن انجام می‌شود.

نکته مهم : در سمت Backend پس از دریافت subscriber_id در اندپوینت مدنظرتان (وب سرویس مد نظرتان جهت دریافت subscriber_id) لطفا ابتدا بررسی کنید که چنین subscriber_id ای در دیتابیس شما از قبل وجود دارد یا خیر، اگر از قبل وجود دارد نیازی به افزودن subscriber_id به شکل تکراری در دیتابیس نیست. اگر وجود ندارد کافی است فقط subscriber_id را به عنوان مشترک جدید در نظر بگیرید و در دیتابیس ذخیره کنید
<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>
همانطور که گفته شد لطفاً دقت کنید که نباید دو مرتبه <script src="https://sdk.pushfa.com/notification-v2.js?api_public_key=YOUR_PUBLIC_KEY" type="module"></script> را قرار دهید.

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

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

enable-push نام دکمه همین نمونه در سایت شماست؛ دکمه داخلی پوشفا نیست. برای کادر سفارشی خودتان، همین کد کلیک را به دکمه تأیید کادر وصل کنید و شناسه enable-push را در همه جای نمونه با id دکمه خود جایگزین کنید؛ دکمه تکراری نسازید. اگر زمان نمایش کادر را خودتان کنترل می‌کنید autoPrompt: false را نگه دارید. اگر با custom_soft_prompt از رویداد pushfaCustomPromptRequest برای نمایش کادر استفاده می‌کنید، خاموش‌کردن نمایش خودکار را بردارید. صرف کلیک روی دکمه تأیید کادر کافی نیست؛ ارسال بعد از تأیید مجوز مرورگر انجام می‌شود.
<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>

دریافت و ذخیره توکن 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) به‌صورت مستقیم

در هر لحظه میتوانید مقادیر getToken()را که حاوی شناسه fcm است و null نبودن آن به منزله سابقه پذیرش پوش توسط کاربر است و همینطور getSubscriberId() را که حاوی مقدار subscriber_id بوده فارغ از اینکه کاربر شما هنوز عضویت پوش نوتیفیکیشن را تایید کرده است یا خیر را دریافت کنید، بنابراین فراخوانی و خواندن getSubscriberId() به‌تنهایی پذیرش Push توسط کاربر را ثابت نمی‌کند. در صورتی که نیاز به این کار دارید دستورالعمل های بالایی را استفاده و اجرا کنید یا حداقل این نکته را در نظر بگیرید که در فراخوانی همزمان getSubscriberId() و getToken() هیچ یک از آن ها نباید null باشند و هر دو باید مقدار داشته باشند در چنین شرایطی میتوان برداشت کرد که کاربر از قبل دریافت پوش را تایید کرده است سپس ارسال های آتی را با subscriber_id انجام دهید . کاربرد اصلی getSubscriberId() به تنهایی این مورد است که در هر لحظه با فراخوانی آن میتوان مقدار subscriber_id را پیدا کرده و در صورتی که کاربری لاگین کرده بود بلافاصله با ارسال این مقدار (در صورت عدم null بودن) به یک وب سرویس از بک اند اتصال کاربر-suscriber_id را به شکل ضمنی در دیتابیسان برقرار کنید و با این کار متوجه شوید که این subscriber_id برای کدام کاربرتان است.

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