SDK v2

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

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

کاربران تا زمانی که با 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);
  // برای هویت و ارسال سروری، 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)
Ctrl+I