WooSpinBooster — How To

Summary

Add a gamified “spin-to-win” wheel to WooCommerce. Offer coupons, freebies, links to special pages, or a simple “Try again.” Lightweight, skinnable, cache-friendly—built to convert.

---

Prerequisites

• WordPress + WooCommerce (latest).
• A modern theme (Block or Classic).
• (Optional) Mailchimp/Klaviyo key if you gate spins by email.

---

Install & Activate

1. Plugins → Add New → Upload Plugin → upload ZIP → Activate.
2. Go to WooCommerce → Settings → Spin Booster.

---

Quick Start (Display)

You can show the wheel as a modal or inline.

A) Modal (auto-show on page load)

1. Spin Booster → Display → Modal → Enable Auto-Show.
2. Choose Delay (e.g., 3s) and Pages (Shop, Cart, custom, etc.).
3. Save and visit the chosen page to test.

B) Inline (shortcode/block)

• Gutenberg block: add “Spin Booster Wheel.”
• Shortcode (example—check your settings for the exact tag): [spin_booster] Place it on a landing page or in a promo section.

---

Configure the Wheel

1) Slices & Outcomes

• Go to Spin Booster → Wheel → Slices.
• Add slices (8–16 recommended). Each slice has:
  • Label (e.g., “10% Off”, “Free Shipping”, “Try Again”, “Secret Link”)
  • Outcome Type: Coupon / Free Shipping / Free Product / Link / Try Again / Custom
  • Probability/Weight (e.g., 20 for common prizes, 5 for rare)
  • Consumes a spin? (Disable for “Try Again” so users can immediately spin again.)
  • Optional JSON payload (for advanced actions—see below)

Example JSON payload (Link prize)

{
  "url": "/vip-special",
  "open": "new",
  "note": "VIP splash page"
}

2) Coupons & Rewards

• Coupon prize: pick an existing Woo coupon or let the plugin generate a unique code.
• Free shipping/product: map to a qualifying coupon or a free line item rule.
• Link prize: add the URL in the JSON payload or the slice’s link field.

3) Email Gate (Optional)

• Spin Booster → Gate/Leads → Require Email.
• Choose Mailchimp/Klaviyo (enter API + Audience/List ID) or Local DB (stored in wsb_leads).
• Toggle Double Opt-In if required.

4) Limits & Fairness

• Max spins per user/day (cookie + email fallback).
• Per-slice “consumes a spin” (disable for Try Again).
• Daily reset time window.

---

Effects & Styling

Visuals

• Wheel size (desktop/mobile), colors, slice borders, center button text.
• Sparkles toggle and intensity.
• Result banner: background, text, shadow on/off.

Pointer orientation

• Setting: Pointer → Orientation = Down.
• If you need CSS: .wsb-pointer { transform: rotate(180deg); transform-origin: 50% 0; }

Sounds

• Toggle Spin, Tick, Win sounds.
• Provide your own .mp3/.ogg assets if you want custom audio.

---

Caching/CDN (Important)

Exclude these from full-page cache and any “combine/minify JS” breaking rules:

/?add-to-cart=*
/?wc-ajax=*
/cart/
/checkout/
/wp-json/wc-spin-booster/v1/*

If you auto-apply coupons, make sure your cache plugin/CDN doesn’t cache personalized cart pages for logged-out users.

---

Troubleshooting

1) “CanvasRenderingContext2D.arc: Negative radius”

Cause: The canvas renders while its container is hidden (e.g., a modal not yet opened) or width computes to 0, producing a negative radius in spin.js.
Fix:

• Ensure the wheel initializes after the modal opens (use the plugin’s “Init on Modal Open” option).
• If customizing code, clamp radius and re-measure on open: const pad = 20; const w = canvas.clientWidth || 300; const h = canvas.clientHeight || 300; const radius = Math.max(60, Math.min(w, h) / 2 - pad); // avoids negative
• Call the plugin’s resize/redraw method on the modal “shown” event.

2) “I can’t see the effects (sparkles/sounds)”

• Check Effects toggles.
• If you use JS minification/deferral, exclude the plugin’s JS from “defer” to ensure timing isn’t broken.
• Safari/iOS requires a user gesture before playing audio—ensure the first spin is user-initiated or enable the “prompt before spin” button.

3) Pointer points the wrong way

• Use Pointer → Orientation = Down or the CSS snippet above.

4) Text has an unwanted shadow under the result

• Result Banner → Shadow = Off, or: .wsb-result, .wsb-result * { text-shadow: none !important; box-shadow: none !important; }

5) Coupons not applying

• Confirm coupon is valid, not expired, and permitted for products/categories in cart.
• If page caching is aggressive, auto-apply flows may be blocked—use the cache exclusions above and purge.

6) “Try Again” consumes a spin

• Edit that slice → Consumes a spin = Off. Save and test.

---

Developer Notes (Hooks)

Actions

• wsb_spin_awarded( $user_id, $slice ) – fires when a prize is awarded.
• wsb_lead_captured( $lead ) – fires after email capture.

Filters

• wsb_validate_spin – return false to block a spin based on custom logic.
• wsb_render_prize_payload – alter JSON payload before delivering the result.

(Names are illustrative; check your plugin’s exact hook list under Settings → Developers.)

---

Uninstall

• Deactivate → Delete from Plugins.
• In Settings → Advanced, toggle Remove data on uninstall if you want to wipe slices, leads, and logs.

---

FAQ Snippets (optional add-on to this article)

Can I stack multiple rewards?
Yes—use multiple slices or a “Bundle” slice that applies more than one action in a custom handler.

Will this slow my site?
No—assets are small and only load where the wheel is used. Keep cache rules above for best results.

Can I deep-link to a prize page?
Yes—use the Link outcome with a URL in the slice or JSON payload.

---