SDK v2
متدهای SDK v2
فهرست کامل متدهای window.Pushfa که در مرورگر قابل فراخوانی هستند: عضویت، توکن، تاپیک، شناسه و رویدادها.
عضویت و توکن
متدهای اصلی برای درخواست اجازه از مرورگر و دریافت توکن مشترک.
| متد | توضیح | نوع خروجی |
|---|---|---|
| window.Pushfa.showPrompt() | کادر پیشدرخواست پوشفا را نمایش میدهد. true اگر نمایش داده شود. | boolean |
| window.Pushfa.shouldShowPrompt() | بررسی میکند نمایش کادر ممکن است یا نه (بلاک نشده، iOS نیست، …) | boolean |
| window.Pushfa.requestPermission() | مستقیماً permission مرورگر را درخواست میکند و توکن را برمیگرداند. | Promise<string|null> |
| window.Pushfa.getToken() | توکن FCM ذخیرهشده فعلی را میخواند (یا null اگر عضو نشده). | string|null |
| window.Pushfa.getSubscriberId() | شناسه ثابت مشترک این دستگاه را برمیگرداند. | string|null |
| window.Pushfa.closePrompt() | کادر درخواست پوشفا را میبندد. | void |
| window.Pushfa.cancelAutoPrompt() | تایمر یا listener نمایش خودکار را لغو میکند. | void |
// دریافت توکن بعد از عضویت
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) و شناسههای سفارشی
متصل کردن توکن مرورگر به شناسه داخلی سایت شما.
کاربران تا زمانی که با Alias ID یا Custom Alias شناسایی نشوند، ناشناس باقی میمانند.
| متد | توضیح | نوع خروجی |
|---|---|---|
| window.Pushfa.setUserAliasID(id) | توکن را به یک شناسه اصلی کاربر وصل میکند (مانند 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 |
window.addEventListener('pushfaTokenChange', (e) => {
console.log('توکن جدید:', e.detail);
// توکن را در سرور ذخیره کنید
});
window.addEventListener('pushfaSubscriberId', (e) => {
console.log('subscriber id:', e.detail);
});
ارسال رویداد RetenX
برای فعالسازی کمپینهای ریتنشن خودکار، رویدادهای رفتاری کاربر را با این متد ارسال کنید.
// رویداد شروع کمپین
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.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) |