متدهای JavaScript پوشفا؛ مرجع توابع SDK وب
توابع SDK وب پوشفا و روش استفاده از آنها را ببینید؛ مدیریت عضویت، هویت و ارتباط سایت با سرویس پوش همراه با نمونه کد و نکات اجرا.
عضویت و توکن
این جدول متدهای مرتبط با نمایش جریان عضویت، درخواست اجازه دریافت اعلان و خواندن اطلاعات دستگاه در SDK وب را خلاصه میکند. از ستون «کاربرد» برای انتخاب متد مناسب و از ستون «خروجی» برای مدیریت مقدار بازگشتی آن در کد خود استفاده کنید.
| متد | توضیح | نوع خروجی |
|---|---|---|
| window.Pushfa.showPrompt() | کادر پیشدرخواست پوشفا را نمایش میدهد. true اگر نمایش داده شود. | boolean |
| window.Pushfa.shouldShowPrompt() | بررسی میکند نمایش کادر ممکن است یا نه (بلاک نشده، iOS نیست، …) | boolean |
| window.Pushfa.requestPermission() | مستقیماً اجازه دریافت اعلان مرورگر را درخواست میکند و توکن را برمیگرداند. | Promise<string|null> |
| window.Pushfa.getToken() | توکن فنی فعلی را میخواند (یا null)؛ برای دریافت، ذخیره و ارسال، getSubscriberId() پایدارتر و توصیهشده است. | string|null |
| window.Pushfa.getSubscriberId() | شناسه ثابت مشترک این دستگاه؛ گزینه پیشنهادی برای دریافت، ذخیره در سرور و ارسال با subscriber_id یا subscriber_ids[]. | string|null |
| window.Pushfa.closePrompt() | کادر درخواست پوشفا را میبندد. | void |
| window.Pushfa.cancelAutoPrompt() | تایمر یا listener نمایش خودکار را لغو میکند. | void |
| window.Pushfa.snoozePrompt(days) | برای پرامپت سفارشی استفاده میشود و نمایش دوباره درخواست را تا چند روز عقب میاندازد. | boolean |
| window.Pushfa.showIosInstallPrompt(days) | در iOS 16.4+ راهنمای Add to Home Screen را نمایش میدهد؛ بدون پارامتر بعد از بستن دیگر نمایش داده نمیشود. | boolean |
// دریافت توکن بعد از عضویت
const token = await window.Pushfa.requestPermission();
console.log('token:', token);
// دریافت Subscriber ID
const subId = window.Pushfa.getSubscriberId();
console.log('subscriber id:', subId);
// نمایش دستی کادر عضویت
const shown = window.Pushfa.showPrompt();
if (!shown) {
// کاربر قبلاً رد کرده — مستقیم permission بگیر
await window.Pushfa.requestPermission();
}
مدیریت تاپیکها
عضو/خارج کردن دستگاه از تاپیک و خواندن لیست تاپیکها.
| متد | توضیح | نوع خروجی |
|---|---|---|
| window.Pushfa.subscribeTopic(uuid) | دستگاه فعلی را عضو تاپیک میکند. | Promise<void> |
| window.Pushfa.unSubscribeTopic(uuid) | دستگاه فعلی را از تاپیک خارج میکند. | Promise<void> |
| window.Pushfa.getDeviceTopics() | لیست UUID تاپیکهای ذخیرهشده روی همین مرورگر را برمیگرداند. | Promise<string[]> |
await window.Pushfa.subscribeTopic('TOPIC-UUID');
await window.Pushfa.unSubscribeTopic('TOPIC-UUID');
const myTopics = await window.Pushfa.getDeviceTopics();
console.log(myTopics); // ['uuid1', 'uuid2']
شناسه مستعار (Alias) و شناسههای سفارشی
متصل کردن توکن مرورگر به شناسه داخلی سایت شما.
| متد | توضیح | نوع خروجی |
|---|---|---|
| window.Pushfa.setUserAliasID(id) | توکن را به Alias عادی و اصلی کاربر وصل میکند (همان شناسه کاربر در سیستم شما (External ID)). | Promise<void> |
| window.Pushfa.getUserAliasID() | شناسه مستعار ذخیرهشده را برمیگرداند. | string|null |
| window.Pushfa.addAlias(label, value) | یک شناسه سفارشی برچسبدار اضافه میکند. | Promise<void> |
| window.Pushfa.addAliases(map) | چند شناسه سفارشی را با یک فراخوانی اضافه میکند. | Promise<void> |
| window.Pushfa.removeAlias(label) | یک شناسه سفارشی را با برچسب حذف میکند. | Promise<void> |
| window.Pushfa.removeAliases(labels[]) | چند شناسه سفارشی را با یک فراخوانی حذف میکند. | Promise<void> |
| window.Pushfa.getAliases() | همه شناسههای سفارشی ذخیرهشده را برمیگرداند. | object |
// شناسه اصلی کاربر (بعد از login)
await window.Pushfa.setUserAliasID('USER-123');
// شناسههای سفارشی (Custom Aliases)
await window.Pushfa.addAlias('crm_id', 'CRM-456');
await window.Pushfa.addAliases({ order_id: '9090', tier: 'gold' });
const aliases = window.Pushfa.getAliases();
// { crm_id: 'CRM-456', order_id: '9090', tier: 'gold' }
await window.Pushfa.removeAlias('order_id');
رویدادها
رویدادهای browser که SDK پوشفا dispatch میکند.
| رویداد | توضیح | نحوه گوش دادن |
|---|---|---|
| pushfaTokenChange | هر زمان توکن FCM ایجاد یا تغییر کند اجرا میشود. مقدار در event.detail است. | window.addEventListener |
| pushfaSubscriberId | پس از آماده شدن شناسه ثابت مخاطب (Subscriber ID) اجرا میشود. مقدار در event.detail است. | window.addEventListener |
| pushfaCustomPromptRequest | وقتی ظاهر درخواست روی پرامپت سفارشی سایت باشد و زمان نمایش درخواست برسد اجرا میشود. UI خودتان را در پاسخ به این رویداد نمایش دهید. | window.addEventListener |
window.addEventListener('pushfaTokenChange', (e) => {
console.log('توکن جدید:', e.detail);
// برای هویت و ارسال سروری، Subscriber ID را با getSubscriberId() دریافت و ذخیره کنید
});
window.addEventListener('pushfaSubscriberId', (e) => {
console.log('subscriber id:', e.detail);
});
window.addEventListener('pushfaCustomPromptRequest', () => {
document.querySelector('#my-soft-prompt').hidden = false;
});
ارسال رویداد RetenX
برای فعالسازی کمپینهای ریتنشن خودکار، رویدادهای رفتاری کاربر را با این متد ارسال کنید. SDK ابتدا شناسه ثابت مخاطب (Subscriber ID) دستگاه را همراه رویداد میفرستد؛ در درخواستهای سروری از کلید subscriber_id استفاده کنید.
// رویداد شروع کمپین
await window.Pushfa.event('add_to_cart', { product_id: 123, price: 480000 });
// رویداد پایان کمپین (کمپین را لغو میکند)
await window.Pushfa.event('checkout_completed');
نامهای قدیمی (سازگاری پسرو)
برای سازگاری با پروژههای قدیمیتر، نامهای زیر هنوز کار میکنند اما توصیه میشود به window.Pushfa.* مهاجرت کنید.
| نام قدیمی | معادل جدید |
|---|---|
| window.pushfaButton() | window.Pushfa.showPrompt() |
| window.shouldShowPushfaButton() | window.Pushfa.shouldShowPrompt() |
| window.getPushfaToken() | window.Pushfa.getToken() |
| window.getPushfaSubscriberId() | window.Pushfa.getSubscriberId() |
| window.showPushfaIosInstallPrompt(days) | window.Pushfa.showIosInstallPrompt(days) |
| window.pushfaSnoozePrompt(days) | window.Pushfa.snoozePrompt(days) |
| window.subscribeTopic(uuid) | window.Pushfa.subscribeTopic(uuid) |
| window.unSubscribeTopic(uuid) | window.Pushfa.unSubscribeTopic(uuid) |
| window.getDeviceTopics() | window.Pushfa.getDeviceTopics() |
| window.setUserAliasID(id) | window.Pushfa.setUserAliasID(id) |
| window.getUserAliasID() | window.Pushfa.getUserAliasID() |
| window.PushfaRetenXEvent(name, p) | window.Pushfa.event(name, p) |