گردونه شانس وب‌تنان
افزونه فارسی گردونه شانس با ورود سریع، پاپ‌آپ هوشمند، ووکامرس، پیامک IPPanel، رابط واکنش‌گرا و تنظیمات حرفه‌ای.
by وب تنان · github.com/webtanan-sketch/webtanan-lucky-wheel · website
Install
No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:
wp plugin install https://github.com/webtanan-sketch/webtanan-lucky-wheel/archive/refs/heads/main.zip🎯 گردونه شانس وب‌تنان
Webtanan Lucky Wheel
افزونه فارسی و حرفه‌ای وردپرس برای کمپین گردونه شانس، جمع‌آوری لید، کوپن WooCommerce و پیامک جایزه
توسعه و نگهداری: وب تنان
معرفی
گردونه شانس وب‌تنان برای اجرای کمپین‌های فروش، جذب لید و باشگاه مشتریان در وردپرس طراحی شده است. انتخاب جایزه، کنترل تعداد شانس، ثبت نتیجه و ساخت کوپن در سمت سرور انجام می‌شود و رابط کاربری فقط نتیجه معتبر سرور را نمایش می‌دهد.
کاربر مهمان فقط نام و شماره موبایل را وارد می‌کند. اگر کاربر از قبل در WordPress لاگین باشد، فرم حذف می‌شود و کاربر مستقیم به گردونه می‌رود.
نسخه 1.5.0 تمرکز ویژه‌ای روی سرعت ادراکی، واکنش آنی رابط، ساختار بارگذاری اصولی وردپرس و شخصی‌سازی رابط دارد.
✨ امکانات نسخه 1.5.0
| قابلیت | توضیح |
|---|---|
| واکنش آنی فرم | پس از ثبت نام و موبایل، مرحله گردونه بلافاصله نمایش داده می‌شود و اعتبارسنجی سرور در پس‌زمینه تکمیل می‌شود |
| چرخش فوری | حرکت گردونه از همان لحظه کلیک آغاز می‌شود و منتظر پاسخ AJAX نمی‌ماند |
| شانس لحظه‌ای | تعداد شانس در همان لحظه کلیک تغییر می‌کند و سپس با مقدار قطعی سرور تطبیق داده می‌شود |
| اصلاح ۱۸۰ درجه | جهت متن خانه‌ها پیش از توقف نهایی بر اساس زاویه واقعی مقصد اصلاح می‌شود |
| متن دکمه‌ها | متن دکمه پاپ‌آپ، ورود، چرخش و تأیید نتیجه از مدیریت قابل تغییر است |
| لوگوی مرکز | امکان انتخاب تصویر از Media Library و نمایش دایره‌ای آن در مرکز گردونه |
| Bootstrap سبک‌تر | کنترلرهای Admin، AJAX و Front-end فقط در Context موردنیاز بارگذاری می‌شوند |
| Cache درون درخواست | تنظیم رنگ‌ها و لیست پردازش‌شده جوایز در هر درخواست فقط یک‌بار ساخته می‌شوند |
| پیامک غیرهمزمان | ارسال IPPanel خارج از درخواست چرخش و با Action Scheduler یا WP-Cron انجام می‌شود |
| ورود مهمان | فقط نام و موبایل؛ بدون ساخت حساب WordPress |
| کاربر لاگین‌شده | ورود مستقیم به گردونه بدون نمایش فرم |
| پاپ‌آپ هوشمند | صفرشانس‌ها پاپ‌آپ نمی‌بینند و پس از ریست روزانه دوباره امکان نمایش دارند |
| شانس روزانه | فقط حساب‌هایی که شانسشان صفر شده در روز بعد ریست می‌شوند |
| WooCommerce | ساخت کوپن یک‌بارمصرف با تاریخ انقضا و تخفیف ثابت یا درصدی |
| IPPanel | ارسال کد تخفیف برنده با Pattern API و تاریخ انقضای شمسی |
| رنگ‌بندی | تغییر رنگ‌های اصلی رابط بدون دست‌کاری CSS |
| فونت قالب | رابط عمومی از فونت قالب فعال WordPress پیروی می‌کند |
⚡ معماری و کارایی
نسخه 1.5 به‌جای بارگذاری همه کلاس‌های رابط در تمام درخواست‌ها، فایل‌ها را متناسب با Context بارگذاری می‌کند:
- درخواست AJAX: کنترلر AJAX
- مدیریت WordPress: صفحات مدیریت و تنظیمات
- Front-end: شورت‌کد و دارایی‌های عمومی
- Cron: فقط سرویس‌های موردنیاز پردازش زمینه‌ای
CSS و JavaScript عمومی نیز فقط زمانی Enqueue می‌شوند که شورت‌کد گردونه واقعاً Render شود.
ارسال پیامک خارجی در مسیر اصلی چرخش انجام نمی‌شود؛ اگر WooCommerce Action Scheduler موجود باشد، پیامک به صف آن سپرده می‌شود و در غیر این صورت WP-Cron به‌عنوان Fallback استفاده می‌شود. این کار مانع اثرگذاری تأخیر سرویس پیامکی روی پاسخ گردونه می‌شود.
🧭 تجربه کاربر
کاربر مهمان
باز شدن کمپین
↓
نام + شماره موبایل
↓
نمایش فوری مرحله گردونه
↓
تأیید امن اطلاعات در سرور
↓
کلیک روی چرخش
↓
شروع فوری انیمیشن + کاهش لحظه‌ای شانس
↓
دریافت نتیجه قطعی سرور
↓
توقف در مرکز جایزه + تطبیق تعداد شانسکاربر لاگین‌شده
باز شدن کمپین
↓
تشخیص خودکار حساب WordPress
↓
بدون فرم
↓
نمایش مستقیم گردونه و تعداد شانس🎛 تنظیم متن دکمه‌ها و لوگوی مرکز
از مسیر زیر:
گردونه شانس ← رابط و دکمه‌ها
موارد زیر قابل مدیریت هستند:
- متن دکمه بازکردن پاپ‌آپ
- متن دکمه شرکت در قرعه‌کشی
- متن دکمه چرخاندن گردونه
- متن دکمه تأیید نتیجه
- تصویر مرکز گردونه
لوگو از Media Library وردپرس انتخاب و با شناسه Attachment ذخیره می‌شود. در Front-end تصویر به‌صورت دایره‌ای و با object-fit: cover داخل مرکز گردونه قرار می‌گیرد. اگر تصویری انتخاب نشده باشد، متن «شانس» نمایش داده می‌شود.
پارامتر button_text در شورت‌کد همچنان می‌تواند متن دکمه پاپ‌آپ همان نمونه را Override کند.
🚀 نصب
- افزونه را در
wp-content/plugins/قرار دهید یا ZIP آن را از مدیریت WordPress نصب کنید. - افزونه گردونه شانس وب‌تنان را فعال کنید.
- از گردونه شانس ← تنظیمات گردونه عنوان، تعداد شانس و وضعیت کمپین را تنظیم کنید.
- از گردونه شانس ← مدیریت جوایز جایزه‌ها، احتمال‌ها و تاریخ انقضا را تنظیم کنید.
- از گردونه شانس ← ظاهر و رنگ‌بندی رنگ‌ها را تنظیم کنید.
- از گردونه شانس ← رابط و دکمه‌ها متن‌ها و لوگوی مرکز را تنظیم کنید.
- در صورت نیاز، گردونه شانس ← پیامک IPPanel را تکمیل کنید.
🧩 شورت‌کدها
نمایش عادی:
[webtanan_lucky_wheel]پاپ‌آپ:
[webtanan_lucky_wheel popup="1"]متن اختصاصی برای یک پاپ‌آپ:
[webtanan_lucky_wheel popup="1" button_text="شانس خودت را امتحان کن"]بازشدن خودکار بعد از ۲.۵ ثانیه:
[webtanan_lucky_wheel popup="1" auto_open="1" delay="2500"]delay بر حسب میلی‌ثانیه است.
🔄 ریست روزانه شانس
در شروع روز جدید:
- مهمان‌هایی که
remaining_attempts <= 0دارند به تعداد شانس پیش‌فرض برمی‌گردند. - کاربران WordPress که شانسشان صفر شده نیز ریست می‌شوند.
- کاربری که هنوز شانس دارد دست‌کاری نمی‌شود.
- پاپ‌آپ برای صفرشانس‌ها در همان روز مخفی می‌ماند.
WP-Cron و کنترل اولین درخواست روز جدید هر دو برای حفظ این رفتار استفاده می‌شوند.
📲 IPPanel Edge API
تنظیمات پیامک از مسیر گردونه شانس ← پیامک IPPanel در دسترس است.
امکانات:
- Base URL
- API Key / Token
- شماره ارسال‌کننده
- چند پترن مستقل
- انتخاب پترن فعال
- کد پترن
- نام پارامترها
- متن قابل مدیریت
متغیرهای متن:
{name} نام کاربر
{coupon} کد تخفیف
{expiry} تاریخ انقضا شمسی
{reward} عنوان جایزهارسال جایزه در نسخه 1.5 به‌صورت Queue/Background انجام می‌شود تا سرویس خارجی IPPanel سرعت تجربه چرخش را کاهش ندهد.
🎡 جهت متن و توقف گردونه
نتیجه در PHP انتخاب می‌شود. پس از دریافت مقصد واقعی، JavaScript زاویه نهایی را محاسبه می‌کند و پیش از توقف، جهت خوانایی هر نوشته را برای موقعیت نهایی مشخص می‌کند. بنابراین Flip صدوهشتاددرجه در لحظه توقف آماده است و بعد از پایان انیمیشن با تأخیر اعمال نمی‌شود.
نمایشگر سپس دقیقاً به مرکز سگمنت انتخاب‌شده می‌رسد.
🔐 امنیت
کنترل‌های امنیتی اصلی:
- WordPress Nonce برای درخواست‌های AJAX
manage_optionsو Nonce برای تنظیمات مدیریت- Sanitization و Validation ورودی‌ها
- Rate Limit بر اساس IP
- شناسه یکتای درخواست برای جلوگیری از Replay
- Lock کوتاه‌مدت برای جلوگیری از Double Spin
- کنترل قطعی تعداد شانس در PHP
- انتخاب وزنی با
random_int - توکن هش‌شده برای مهمان
- API Key پیامک فقط در سمت سرور
- نتیجه جایزه فقط در سمت سرور تعیین می‌شود
هیچ نرم‌افزار وب را نمی‌توان به‌صورت مطلق «۱۰۰٪ امن» تضمین کرد؛ هدف این پروژه رعایت اصول WordPress و کاهش سطح حمله با کنترل‌های چندلایه است.
🗂 ساختار اصلی
webtanan-lucky-wheel/
├── admin/
│ ├── css/
│ └── js/
├── includes/
│ ├── class-admin.php
│ ├── class-ajax.php
│ ├── class-appearance.php
│ ├── class-database.php
│ ├── class-guest-admin.php
│ ├── class-plugin.php
│ ├── class-rewards.php
│ ├── class-shortcode.php
│ ├── class-sms.php
│ ├── class-ux-settings.php
│ ├── class-wallet.php
│ ├── class-wheel-engine.php
│ └── class-woocommerce.php
├── public/
│ ├── css/
│ ├── js/
│ └── templates/
├── README.md
└── webtanan-lucky-wheel.php🧪 بررسی فنی نسخه 1.5.0
- PHP Syntax برای فایل‌های تغییرکرده بررسی شده است.
- JavaScript Syntax برای اسکریپت گردونه و Media Picker بررسی شده است.
- منطق نتیجه امن سمت سرور حفظ شده است.
- مقدار خوش‌بینانه شانس در Front-end همیشه پس از پاسخ، با مقدار قطعی سرور Reconcile می‌شود.
- ارسال پیامک از Critical Path چرخش خارج شده است.
Changelog
1.5.0
- Context-aware Bootstrap و کاهش بارگذاری غیرضروری
- شروع فوری حرکت گردونه در لحظه کلیک
- نمایش و کاهش لحظه‌ای تعداد شانس با Reconciliation سرور
- انتقال فوری فرم به مرحله گردونه
- اصلاح Flip صدوهشتاددرجه پیش از توقف نهایی
- مدیریت متن چهار دکمه اصلی
- انتخاب لوگوی دایره‌ای مرکز گردونه از Media Library
- Cache تنظیم رنگ و لیست جوایز در همان درخواست
- ارسال غیرهمزمان پیامک IPPanel
1.4.0
- ورود مستقیم کاربر لاگین‌شده
- ریست روزانه صفرشانس‌ها
- پاپ‌آپ هوشمند
- اتصال IPPanel و پترن‌ها
- تاریخ انقضای شمسی پیامک
مجوز
MIT — جزئیات در فایل LICENSE.