SDK v2

متدهای JavaScript پوشفا؛ مرجع توابع SDK وب

توابع SDK وب پوشفا و روش استفاده از آن‌ها را ببینید؛ مدیریت عضویت، هویت و ارتباط سایت با سرویس پوش همراه با نمونه کد و نکات اجرا.

عضویت و توکن

این جدول متدهای مرتبط با نمایش جریان عضویت، درخواست اجازه دریافت اعلان و خواندن اطلاعات دستگاه در SDK وب را خلاصه می‌کند. از ستون «کاربرد» برای انتخاب متد مناسب و از ستون «خروجی» برای مدیریت مقدار بازگشتی آن در کد خود استفاده کنید.

برای ذخیره در بک‌اند، نمونه کامل مناسب سایت خود را در صفحه «دریافت و ذخیره شناسه» بردارید: سافت پرامپت آماده با pushfaTokenChange؛ دکمه اختصاصی با requestPermission. فقط توکن غیرخالی، اجازه granted و شناسه غیرخالی را بپذیرید.
متدتوضیحنوع خروجی
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) و شناسه‌های سفارشی

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

کاربران تا زمانی که با 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 پس از ثبت موفق توکن جدید یا تغییر توکن در پوشفا اجرا می‌شود. 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)
Ctrl+I