نحوه دریافت و ذخیره توکن های 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 را برای ذخیرهسازی به بکاند سایتتان بفرستید. با این روش، فقط شناسه بازدیدکنندگانی را برای ارسال پوش ذخیره میکنید که دستکم یکبار مجوز دریافت پوش دادهاند.
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 Code | error_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() نیز همین مسیر را اجرا کنید.
دیاگرام دریافت، ذخیره و ارسال با شناسه مشترک
error_code همان شناسه را با جدول بالا مقایسه کنید. وضعیت HTTP در تصویر خلاصه شده است. پاسخ ۴۱۰ علت نامعتبر شدن توکن را مشخص نمیکند و پاسخ ۲۰۰ هم میتواند شامل شناسههای ردشده باشد.
استعلام وضعیت شناسههای قبلی از سرور پوشفا
برای تأیید وضعیت ثبتشده در پوشفا، این درخواست را فقط از بکاند خود و با کلید عمومی و خصوصی همان سرویس بفرستید. subscriber_ids در هر درخواست باید بین ۱ تا ۲۵ شناسه داشته باشد. نتیجه هر شناسه در data.subscribers برمیگردد. این استعلام، آخرین وضعیت شناختهشده سرور را نشان میدهد؛ اگر کاربر همین حالا مجوز مرورگر را تغییر داده و هنوز ثبت یا ارسال تازهای انجام نشده باشد، ممکن است این تغییر هنوز به سرور نرسیده باشد.
| فیلدهای هر آیتم در 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 پوشفا ارسال کنید. به بیان دقیقتر، شناسه مستعار که شناسهای در سیستم شماست به پوشفا ارائه میشود و پوشفا آن را به کاربر جاری متصل میکند؛ ارسال نیز با ارائه همین شناسه بهعنوان مقصد انجام میشود. هر زمان تمایل داشته باشید میتوانید این شناسه را حذف کنید؛ در این صورت توکن جاری در مرورگر کاربر دیگر به آن شناسه متصل نخواهد بود. اگر کاربر چند دستگاه (چند توکن) با یک شناسه داشته باشد، پیام به تمام دستگاههایی که آن شناسه به آنها متصل است ارسال میشود و هزینه آن بهصورت گروهی کسر خواهد شد. برای اطلاعات بیشتر، مطالب زیر را مطالعه کنید.