=== io8 Spin & Win ===
Contributors: io8software
Tags: woocommerce, coupons, gamification, promotions, discount
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Turn WooCommerce promotions into a game with a fun, configurable Spin & Win discount wheel.

== Description ==

io8 Spin & Win adds an interactive prize wheel to your WooCommerce store, giving visitors a fun way to win discounts while shopping.

Create your own prize wheel, choose the discounts you want to offer, adjust the relative chances of each prize and decide where and when the promotion appears.

When a visitor spins the wheel, the winning result is selected securely on your WordPress server. Winning discounts are automatically created as WooCommerce coupons ready for the customer to claim.

= Turn promotions into an experience =

Instead of simply displaying another discount message, Spin & Win gives customers something interactive to engage with.

Use it for sales, seasonal promotions, customer rewards, special events or simply to make your WooCommerce store more engaging.

= Configure your own prize wheel =

Create a wheel with between 2 and 12 segments and configure each prize individually.

Prize options include:

* Percentage discounts.
* Fixed-cart discounts.
* No-prize / Try Again segments.
* Custom prize labels.
* Relative winning probabilities.

This gives you control over both the prizes customers can receive and how frequently different results are selected.

= Automatic WooCommerce coupons =

When a customer wins a discount, io8 Spin & Win automatically generates a single-use WooCommerce coupon for the configured prize.

You can also control:

* Minimum cart spend.
* Prize expiry time.
* Customer play interval.
* Campaign start date.
* Campaign end date.

= Choose where the wheel appears =

Display your Spin & Win promotion where it makes sense for your store.

Supported display options include:

* Site-wide.
* Shop pages.
* Product pages.
* Cart page.

= Built for customer engagement =

The frontend experience includes:

* Responsive prize wheel.
* Animated wheel spinning.
* Optional game sounds.
* Celebration effects.
* Confetti.
* Winning and Try Again results.
* Customer prize claiming.
* Desktop and mobile support.

= Administrator Test Mode =

Testing a promotion shouldn't mean waiting for the normal customer play interval.

Administrator Test Mode allows authorised store administrators to spin repeatedly while testing the campaign.

Administrators can also force a configured prize result, making it easy to check every prize and coupon before launching the promotion.

Normal visitors continue to follow the configured play limits.

= Basic campaign statistics =

Keep track of campaign activity from WordPress admin.

io8 Spin & Win records basic aggregate statistics including campaign interactions, spins and wins.

= Secure server-side prize selection =

The browser does not decide which prize a customer receives.

Prize selection is performed by PHP on your WordPress server using the configured relative probabilities. The frontend then animates the wheel to the result returned by the server.

= WooCommerce ready =

io8 Spin & Win integrates directly with WooCommerce and includes a WooCommerce HPOS compatibility declaration.

No external account, cloud service or paid API is required.

== Screenshots ==

1. Spin & Win prize wheel displayed on a WooCommerce storefront, creating an interactive promotional experience for shoppers.
2. Configure wheel prizes, discount values and relative winning probabilities from the WordPress administration area.
3. Reward winning customers with WooCommerce discount coupons generated by Spin & Win.
4. Configure and customise the Spin & Win experience for your WooCommerce promotion.
5. Campaign statistics provide an overview of Spin & Win activity and customer engagement.
6. Responsive Spin & Win experience designed for desktop and mobile shoppers.

== Installation ==

1. Install and activate WooCommerce.
2. Install and activate io8 Spin & Win.
3. Open **Spin & Win** in the WordPress administration area.
4. Configure your campaign and prize wheel.
5. Add the prizes and discount values you want to offer.
6. Configure play limits, prize rules and campaign availability.
7. Choose where the Spin & Win promotion should appear.
8. Save your settings.
9. Visit an enabled storefront page and test the wheel.

Administrator Test Mode can be enabled while setting up your campaign so you can test prizes repeatedly before making the promotion available to customers.

== Frequently Asked Questions ==

= Do I need WooCommerce? =

Yes. io8 Spin & Win is designed for WooCommerce stores and requires WooCommerce to be installed and active.

= Does the browser decide which prize is won? =

No. The winning result is selected by PHP on your WordPress server. The browser then animates the wheel to the result returned by the server.

= What types of prizes can I create? =

You can create percentage discounts, fixed-cart discounts and no-prize / Try Again segments.

= Can I control how likely each prize is to be won? =

Yes. Each wheel segment can be assigned a relative probability, allowing you to control how frequently different results are selected.

= Do the probabilities have to add up to 100? =

No. Prize probabilities are relative weights. They do not need to total 100.

= What happens when a customer wins? =

The plugin generates a single-use WooCommerce coupon for the configured winning discount. The customer can claim the prize and continue shopping.

= Can I set a minimum order value? =

Yes. Use the Minimum Spend setting under the prize rules. Set the value to 0 if you do not want a minimum spend requirement.

= Can prizes expire? =

Yes. You can configure how long generated winning coupons remain valid.

= Can I limit how often someone plays? =

Yes. The campaign includes a configurable play interval.

= Can I schedule a campaign? =

Yes. You can configure campaign start and end dates.

= Where can I display the wheel? =

The wheel can be configured for site-wide display or selected WooCommerce areas including shop, product and cart pages.

= Can I test every prize before launching? =

Yes. Enable Administrator Test Mode.

Authorised administrators can spin repeatedly and optionally force a particular configured prize result. Test Mode does not remove the configured play limits for normal visitors.

= Does Spin & Win work on mobile devices? =

Yes. The frontend wheel is responsive and designed to work on desktop and mobile devices.

= Does the plugin require an external account? =

No. The free plugin runs on your own WordPress and WooCommerce installation.

= Does the plugin use an external API? =

No external API or cloud service is required for the Spin & Win functionality.

== Privacy ==

io8 Spin & Win does not send visitor data to io8 or any external service.

To enforce the configured play interval for guests, the plugin derives a one-way keyed fingerprint from the request IP address and browser user-agent. The resulting hash is used only as part of a temporary WordPress transient key.

The raw IP address and user-agent are not stored by the plugin for this purpose.

For logged-in customers, the WordPress user ID is used for the temporary play-limit mechanism.

The plugin also stores aggregate campaign counters in the WordPress options table and creates WooCommerce coupons when customers win eligible discount prizes.

== Source Code ==

Human-readable source corresponding to the production frontend JavaScript is included with the plugin.

* `assets/js/frontend.js` - production frontend JavaScript.
* `assets/js/frontend.src.js` - human-readable source for `frontend.js`.

No external build tools are required to inspect or modify the included JavaScript source.

== Changelog ==

= 1.0.1 =

* Added human-readable frontend JavaScript source.
* Updated WordPress.org contributor metadata.

= 1.0.0 =

* Initial WordPress.org release.
* Added interactive Spin & Win prize wheel for WooCommerce.
* Added percentage and fixed-cart discount prizes.
* Added no-prize / Try Again segments.
* Added secure server-side prize selection.
* Added automatic WooCommerce coupon generation.
* Added configurable play limits.
* Added minimum-spend controls.
* Added prize expiry controls.
* Added campaign scheduling.
* Added storefront display controls.
* Added Administrator Test Mode.
* Added basic campaign statistics.
* Added responsive frontend experience.
* Added optional game sounds and celebration effects.
* Added WooCommerce HPOS compatibility declaration.