توکن تغییر می‌کند.
ارتباط با مخاطب را حفظ کنید.

شناسه مخاطب را از توکن ارسال جدا کنید

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

مهاجرت در چهار قدم

1. روش عضویت سایتتان را انتخاب کنید

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

2. منتظر تأیید اعلان و ثبت موفق بمانید

   زدن دکمه «بله» در کادر پوشفا به‌تنهایی کافی نیست؛ کاربر باید اجازه اعلان مرورگر را هم بدهد و توکن با موفقیت ثبت شود. نمونه‌های زیر همین مراحل را بررسی می‌کنند و سپس subscriber_id را به سایت شما می‌فرستند.

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

3. شناسه را در بک‌اند، بدون تکرار ذخیره کنید

   در آدرس دریافت شناسه در سایت خودتان، بررسی کنید که این subscriber_id برای همین کاربر و سرویس وجود دارد یا خیر. اگر وجود ندارد، اضافه کنید؛ اگر وجود دارد، رکورد تکراری نسازید. یک کاربر ممکن است با چند دستگاه، چند شناسه داشته باشد.

   توکن قدیمی را با تغییر نام به شناسه تبدیل نکنید. Subscriber ID واقعی را از SDK همان دستگاه یا ستون Subscriber ID در پنل بگیرید و به کاربر درست وصل کنید.

4. ارسال پیام را با شناسه جدید انجام دهید

   برای یک مخاطب، fcm_token را با subscriber_id جایگزین کنید. برای چند مخاطب، آرایه fcm_tokens را با subscriber_ids جایگزین کنید. تغییر بعدی توکن را خود پوشفا مدیریت می‌کند. ابتدا یک پیام به یک مخاطب بفرستید؛ روش قبلی برای مخاطبانی که هنوز شناسه‌شان را ندارید پشتیبانی می‌شود.

کدام نمونه برای سایت شما مناسب است؟

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

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

<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>

<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>

نمونه‌ها با صفحه دریافت و ذخیره شناسه یکسان هستند. اگر کاربر اجازه ندهد یا توکن ثبت نشود، شناسه‌ای ارسال نمی‌کنند.

همان API، شناسه‌ای پایدارتر

نمونه‌ها درخواست کامل هستند. کلیدها و شناسه مخاطب را با مقادیر سرویس خود جایگزین کنید. کلید خصوصی فقط در Backend بماند.

ارسال تکی: POST /api/webservices/send-single-message

{
  "api_public_key": "YOUR_PUBLIC_KEY",
  "api_private_key": "YOUR_PRIVATE_KEY",
  "fcm_token": "CURRENT_FCM_TOKEN",
  "title": "پیام آزمایشی",
  "body": "سلام از پوشفا",
  "send_time": "current"
}

{
  "api_public_key": "YOUR_PUBLIC_KEY",
  "api_private_key": "YOUR_PRIVATE_KEY",
  "subscriber_id": "SUBSCRIBER_UUID",
  "title": "پیام آزمایشی",
  "body": "سلام از پوشفا",
  "send_time": "current"
}

ارسال گروهی: POST /api/webservices/send-group-message

{
  "api_public_key": "YOUR_PUBLIC_KEY",
  "api_private_key": "YOUR_PRIVATE_KEY",
  "subscriber_ids": ["SUBSCRIBER_UUID_1", "SUBSCRIBER_UUID_2"],
  "title": "پیام گروهی",
  "body": "سلام به همراهان پوشفا",
  "send_time": "current"
}

در JSON نام کلید subscriber_ids است و مقدار آن آرایه؛ نگارش subscriber_ids[] برای فرم است. در ارسال به تاپیک، به‌جای آرایه شناسه‌ها از topic استفاده کنید.

پرسش‌های پیش از مهاجرت