متدهای 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() | شناسه ثابت دستگاه یا null؛ وجود آن بهتنهایی پذیرش Push را ثابت نمیکند. برای ذخیره مقصد Push، نمونههای صفحه دریافت شناسه را دنبال کنید. | 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 |
مدیریت تاپیکها
عضو/خارج کردن دستگاه از تاپیک و خواندن لیست تاپیکها.
| متد | توضیح | نوع خروجی |
|---|---|---|
| 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 | پس از ثبت موفق توکن جدید یا تغییر توکن در پوشفا اجرا میشود. event.detail همان توکن است؛ شنونده را پیش از بارگذاری SDK ثبت کنید. | window.addEventListener |
| pushfaSubscriberId | شناسه پروفایل آماده شده است؛ ممکن است قبل از اجازه اعلان اجرا شود و معیار ذخیره مقصد Push نیست. مقدار در event.detail است. | window.addEventListener |
| pushfaCustomPromptRequest | وقتی ظاهر درخواست روی پرامپت سفارشی سایت باشد و زمان نمایش درخواست برسد اجرا میشود. UI خودتان را در پاسخ به این رویداد نمایش دهید. | window.addEventListener |
window.addEventListener('pushfaTokenChange', (e) => {
if (!e.detail || !('Notification' in window) || Notification.permission !== 'granted') return;
const subscriberId = window.Pushfa.getSubscriberId();
if (!subscriberId) return;
// این نمونه توکن و شناسه را نمایش میدهد؛ کد ذخیره کامل در صفحه دریافت شناسه است.
console.log('fcm token:', e.detail);
console.log('subscriber id:', subscriberId);
});
window.addEventListener('pushfaSubscriberId', (e) => {
// آمادهشدن پروفایل بهتنهایی به معنی فعالشدن Push نیست.
console.log('profile 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) |