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
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) و شناسه‌های سفارشی

متصل کردن توکن مرورگر به شناسه داخلی سایت شما.

کاربران تا زمانی که با Alias ID یا Custom 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);
  // توکن را در سرور ذخیره کنید
});

window.addEventListener('pushfaSubscriberId', (e) => {
  console.log('subscriber id:', e.detail);
});

window.addEventListener('pushfaCustomPromptRequest', () => {
  document.querySelector('#my-soft-prompt').hidden = false;
});

ارسال رویداد RetenX

برای فعال‌سازی کمپین‌های ریتنشن خودکار، رویدادهای رفتاری کاربر را با این متد ارسال کنید. SDK ابتدا Subscriber ID پایدار دستگاه را با فیلد subscribe_id همراه رویداد می‌فرستد و اگر در دسترس نباشد از fcm_token استفاده می‌کند.

// رویداد شروع کمپین
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)
محدود به این بخش
Ctrl+I