=== پوشفا | Pushfa Web Push ===
Contributors: pushfa
Tags: web push, push notification, pwa, woocommerce, retenx, firebase
Requires at least: 6.0
Requires PHP: 7.4
Stable tag: 1.1.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

اتصال کامل وردپرس و ووکامرس به وب‌پوش پوشفا؛ بدون ویرایش قالب یا آپلود دستی Service Worker.

== Description ==

افزونه رسمی اتصال WordPress به SDK نسل دوم Pushfa است. Public Key در مرورگر استفاده می‌شود و Private Key فقط در Backend وردپرس باقی می‌ماند.

امکانات:

* نصب خودکار notification-v2.js و ارائه pushfa-messaging-sw.js در ریشه دامنه
* Prompt خودکار یا دستی با دکمه‌های آماده
* همگام‌سازی Login/Logout با External ID opaque مبتنی بر UUID تولیدشده در Backend
* Custom Alias برای ایمیل و موبایل و Bracketهای نام کاربر
* دکمه عضویت و لغو عضویت Topic
* ارسال اعلان از پیشخوان به همه، Topic، Token، Subscriber ID، External ID یا Custom Alias
* ارسال سروری به خریدار سفارش، کاربر وردپرس، فروشنده محصول، Alias یا Subscriber ID با توابع آماده
* گزارش کلیک و تحویل، زمان‌بندی، دکمه‌های اعلان، TTL، Collapse ID، Silent و Additional Data
* ساخت Topic از وردپرس
* ثبت Backend هویت کاربر با External ID تصادفی و `wp_order_ref` برای سفارش مهمان، بدون اتکا به شناسه عددی وردپرس
* ارسال خودکار اعلان در اولین انتشار نوشته، برگه یا محصول با قالب قابل تنظیم
* اعلان درون‌صفحه‌ای برای پیام‌های Foreground
* رویدادهای اختیاری RetenX برای WooCommerce
* پشتیبانی از iOS Web Push/PWA و راهنمای Add to Home Screen
* پشتیبانی از ثابت‌های امن wp-config.php

== Installation ==

1. پوشه pushfa-web-push را ZIP کنید یا فایل ZIP آماده را از بخش افزونه‌ها بارگذاری کنید.
2. افزونه را فعال کنید.
3. از «پوشفا ← تنظیمات» Public Key سرویس Web/PWA را وارد کنید.
4. برای ارسال از پیشخوان، هویت‌گذاری امن Backend، ساخت Topic و RetenX سروری، Private Key را نیز وارد کنید.
5. دامنه سرویس در پنل Pushfa باید دقیقاً با دامنه HTTPS وردپرس یکسان باشد.
6. از «پوشفا ← وضعیت و راهنما» آدرس Service Worker را بررسی کنید.

راهنمای کامل فارسی مدیر و توسعه‌دهنده در فایل `docs/wordpress-guide-fa.md` داخل افزونه و به‌صورت آنلاین در `https://pushfa.com/index/doc/wordpress` قرار دارد.

برای محیط Production بهتر است کلیدها در wp-config.php تعریف شوند:

`define('PUSHFA_API_PUBLIC_KEY', 'YOUR_PUBLIC_KEY');`

`define('PUSHFA_API_PRIVATE_KEY', 'YOUR_PRIVATE_KEY');`

== Shortcodes ==

* `[pushfa_button]` دکمه هوشمند فعال‌سازی اعلان
* `[pushfa_button label="خبرم کن"]` دکمه با متن سفارشی
* `[pushfa_button label="خبرم کن" accept_label="تایید" reject_label="رد" class="my-pushfa-button"]` دکمه با متن سفارشی دکمه‌های تأیید/رد و کلاس CSS
* `[pushfa_topic_button topic="TOPIC_UUID"]` عضویت/لغو عضویت Topic
* `[pushfa_ios_button]` نمایش راهنمای نصب PWA در iPhone/iPad

== Frequently Asked Questions ==

= چرا Service Worker خطای 404 می‌دهد؟ =

افزونه Rewrite را هنگام فعال‌سازی ثبت و پس از ذخیره تنظیمات نوسازی می‌کند. در هاست‌هایی که فایل‌های ناشناختهٔ `.js` را قبل از اجرای وردپرس 404 می‌کنند، اگر document root قابل‌نوشتن باشد یک فایل fallback کوچک نیز در ریشه ساخته می‌شود. فایل فیزیکی هم‌نامِ متعلق به سایت overwrite نمی‌شود.

= چرا در iPhone توکن ساخته نمی‌شود؟ =

iOS 16.4 یا جدیدتر لازم است. کاربر باید سایت را با Safari به Home Screen اضافه کند، آن را از آیکن نصب‌شده باز کند و سپس اجازه اعلان بدهد.

= چرا Alias یا Topic خطای 403 می‌دهد؟ =

مجوز Set/Get/Delete مربوط به Alias، Bracket یا Topic باید در تنظیمات همان سرویس Pushfa فعال باشد.

= Private Key کجا استفاده می‌شود؟ =

فقط در درخواست‌های Backend با `wp_remote_post`. این مقدار هرگز به SDK، HTML یا تنظیمات JavaScript Frontend داده نمی‌شود.

= آیا External ID قابل حدس است؟ =

خیر. افزونه برای هر کاربر یک UUID تصادفی را در Backend وردپرس تولید می‌کند و شناسهٔ عددی کاربر در Alias استفاده نمی‌شود. برای Aliasهای تجاری مانند vendor_id نیز در حالت امن، مجوز Set Alias از JavaScript را خاموش و ثبت را از Backend انجام دهید. برای پاک‌سازی هویت هنگام Logout، مجوز Unset را روشن نگه دارید.

= چرا Permission دوباره نمایش داده نمی‌شود؟ =

اگر کاربر آن را Deny کرده باشد، مرورگر اجازه درخواست مکرر نمی‌دهد. کاربر باید مجوز سایت را از تنظیمات مرورگر تغییر دهد.

= اگر هویت در Local Storage باشد ولی در Pushfa حذف شده باشد چه می‌شود؟ =

افزونه وضعیت واقعی را با Backend امن بررسی و فقط External ID، Custom Alias یا Bracket مفقود را ترمیم می‌کند. Local Storage به‌تنهایی به‌عنوان مدرک همگام‌بودن پذیرفته نمی‌شود.

= Subscriber IDهای نامعتبر ذخیره‌شده چه می‌شوند؟ =

هنگام بازدید کاربر، حداکثر روزی یک‌بار شناسه‌های ذخیره‌شده با Pushfa بررسی می‌شوند. شناسه‌های قدیمیِ حذف‌شده یا فاقد Push معتبر از متای وردپرس پاک می‌شوند؛ شناسهٔ مرورگر جاری و همهٔ داده‌ها در زمان خطای شبکه حفظ می‌شوند.

== Privacy ==

پس از رضایت کاربر، شناسه اشتراک، FCM Token، اطلاعات فنی دستگاه و رویدادهای فعال‌شده به سرویس Pushfa ارسال می‌شوند. مدیر سایت باید این موضوع را در سیاست حریم خصوصی سایت اعلام کند. متن پیشنهادی افزونه در ابزار Privacy Policy وردپرس ثبت می‌شود.

== Changelog ==

= 1.1.1 =

* رفع نمایش مربع خالی به‌جای علامت تیک در بررسی پیکربندی و حذف وابستگی آیکن وضعیت به فونت Dashicons.

= 1.1.0 =

* افزودن استایل استاندارد `pushfa_card` به تنظیمات پرامت پوشفا.
* افزودن کلاس CSS سفارشی به شورت‌کد دکمهٔ فعال‌سازی اعلان.

= 1.0.1 =

* رفع 404 سرویس‌ورکر در هاست‌هایی که Rewrite وردپرس را برای فایل‌های JavaScript عبور نمی‌دهند.
* افزودن fallback استاتیک خودکار در document root قابل‌نوشتن و نوسازی Rewrite پس از ذخیره تنظیمات.
* افزودن ذخیرهٔ امن Subscriber ID برای کاربر و سفارش و هدف‌گیری خریدار/فروشنده از PHP.
* جایگزینی External ID عددی با UUID opaque، حذف Custom Alias تکراری `wp_user_ref` و نگهداری `wp_order_ref` برای سفارش مهمان.
* ترمیم خودکار هویت حذف‌شده در Pushfa، ادغام درخواست‌های تکراری وضعیت و پاک‌سازی امن Subscriber IDهای منقضی از متای وردپرس.
* انتقال امن مالکیت Subscriber هنگام تعویض حساب و پاک‌سازی فقط Alias/Bracketهای متعلق به خود افزونه.

= 1.0.0 =

* انتشار نخست با SDK v2، Worker خودکار، پنل ارسال، Topic، هویت کاربر و WooCommerce RetenX.
