# 🎡 Advanced Spin Wheel Plugin

👉 [Plugin page](https://bubble.io/plugin/advanced-spin-wheel-prize-fortune-1765190694085x474304452590567400)

👉 [Live demo](https://buttercup-plugins.bubbleapps.io/advanced-spin-wheel)

👉 [Demo editor](https://bubble.io/page?id=buttercup-plugins\&tab=Design\&name=advanced-spin-wheel\&type=page\&elements=bTIGz)

{% hint style="info" %}
Need help building your app? [▶️ **Get Free Consultation from Buttercup 💛**](http://buttercupdev.com/?utm_source=docs)
{% endhint %}

***

## Advanced Spin Wheel Plugin

The **Advanced Spin Wheel** plugin helps you add a fully customizable, server-side spin wheel to your Bubble app to increase user engagement through gamification.

It is designed for **secure winner selection**, **weighted probabilities**, and **flexible customization**, making it suitable for real production use.

{% embed url="<https://www.youtube.com/watch?v=_0-51IQyBZs>" %}

***

### ✨ Key Features

* Server-side winner selection (non-manipulable)
* Weighted probabilities for each slice
* Fully customizable design and animation
* Easy workflow integration
* Supports promotions, giveaways, and gamification flows
* Optional hidden weights for equal visual slices

***

### 🚀 Installation

1. Open your Bubble app editor.
2. Go to the **Plugins** tab.
3. Click **Add plugins**.
4. Search for **Advanced Spin Wheel**.
5. Click **Subscribe**.

The plugin will be available immediately after subscription.

***

### 🧱 Adding the Spin Wheel to the Page

1. Go to the **Design** tab.
2. Drag the **Advanced Spin Wheel** element onto your page.
3. Place it anywhere you want.
4. Customize its appearance using the element’s properties:
   * Colors
   * Text styles
   * Animation speed
   * Slice size

***

### 📊 Data Structure (Recommended)

To manage labels and probabilities dynamically, we recommend creating a data type.

#### Wheel Item (Data Type)

| Field Name | Type   | Description                      |
| ---------- | ------ | -------------------------------- |
| Label      | Text   | Text displayed on the wheel      |
| Weight     | Number | Probability weight for the slice |

***

### 🗂 Creating Wheel Items

1. Go to **Data → App Data**.
2. Create items under **Wheel Item**.

Example:

| Label         | Weight |
| ------------- | ------ |
| 50% OFF       | 5      |
| 25% OFF       | 10     |
| Free Shipping | 20     |
| Try Again     | 40     |

> Higher weight = higher chance to win.

***

### 🎨 Configuring Labels & Weights

1. Go back to the **Design** tab.
2. Select the **Advanced Spin Wheel** element.
3. Set **Option Labels** using the `Label` field.
4. Use **Copy Expression** to bind the `Weight` field.
5. Adjust width and height if needed.

***

### ▶️ Creating the Spin Flow

Add a button to trigger the spin.

#### Required Workflow Order

The spin must follow this **exact sequence**:

#### 1️⃣ Start Spin

**Action:** `start_spin`\
Starts the wheel animation.

***

#### 2️⃣ Get Winner Index (Server-Side)

**Action:** `get_winner_index`

* Runs entirely on the server
* Securely selects the winner using weights
* Returns:
  * `winner_index`
  * `winner_label`

***

#### 3️⃣ Stop Spin

**Action:** `stop_spin`

* Stops the animation
* Set **Winner Index** to:

```
Result of step 2's winner_index
```

This ensures the wheel stops on the correct slice.

***

### 🪟 Showing the Result to the User

1. Create a **Popup** in the Design tab.
2. Add a text element inside the popup.
3. Set the popup’s **Type of content** to **Text**.
4. Bind the text dynamically.

#### Workflow Action

Add a workflow action:

**Action:** `Display data in popup text`\
**Data to display:**

```
Result of step 2's winner_label
```

***

### 🔔 Spin Finished Event

Use the plugin event:

**Advanced Spin Wheel → Cycle Finished**

Connect it to:

* **Show Popup**

This ensures the popup opens automatically when the spin ends.

***

### 💾 Saving the Result to the Database

#### Winner Prize (Data Type)

| Field Name | Type       |
| ---------- | ---------- |
| Winner     | User       |
| Item       | Wheel Item |

#### Workflow Action

Add a workflow step:

**Action:** `Create a new thing`\
**Type:** `Winner Prize`

* **Winner:** Current User
* **Item:**

  ```
  Do a search for Wheel Item
  where Label = Result of step 2's winner_label
  ```

***

### 👁 Preview & Test

1. Preview the app.
2. Click **Spin**.
3. Verify:
   * The wheel spins
   * A prize is selected
   * Popup shows the result
   * Data is saved under **Winner Prize**

***

### ⚖️ Hiding Weights (Optional)

You can enable **Hide Option Weights** in the plugin element.

* All slices will appear equal in size
* Weighted probability logic still applies internally

This is useful for fairness perception.

***

### 🎨 Customization Options

The plugin provides extensive customization options, including:

* Slice colors
* Fonts and text styles
* Animation speed
* Visibility controls

Explore the plugin element settings for full control.

***

### 📞 Support

If you have questions, need help, or want to adapt this flow to your product:

👉 Visit [**https://buttercupdev.com**](https://buttercupdev.com/)\
👉 [Book a **free consultation**](http://buttercupdev.com/?utm_source=docs)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.buttercupdev.com/advanced-spin-wheel-plugin.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.