مستندات پوشفا
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)