Lucky Draw Mini App - User Guide

Welcome to the Lucky Draw Mini App. This guide covers both the member-facing draw page (opened from the VIO Member App) and the Lucky Draw Ops Portal (opened from the VIO Admin Portal) for creating events, managing prizes, and tracking results.

Note: This Mini App opens inside the VIO Member App. Members must sign in to their VIO account before joining a draw. Operators access the Ops Portal from the Admin Portal.

---

Table of Contents

1. How to Access
2. Member App Screen Overview
3. Member Experience - Lucky Draw
4. Member Experience - My Rewards
5. Ops Portal - Lucky Draw History
6. Ops Portal - Create / Edit Lucky Draw
7. Ops Portal - Event Dashboard
8. Operational Workflows
9. Troubleshooting
10. Business Rules & Notes

---

1. How to Access

For members (Member App)

1. Open the VIO Member App and sign in with Email or Phone (see Login).
2. From Home, locate Mini programme and tap See all to open the Mini Apps grid (/mini-apps).
3. Find the tile labelled Lucky Draw (label may vary by tenant).
4. Tap the tile to open the draw page. The Mini App loads inside the Member App shell.

Tip: If you are bounced back to the login screen, sign in again and reopen Lucky Draw from Mini programme. Always open the draw from the Member App so your VIO session is passed correctly to the Mini App.

For operators (Lucky Draw Ops Portal)

1. Open the Admin Portal and sign in.
2. From Dashboard or the Mini Apps section, open Lucky Draw.
3. The Lucky Draw Ops Portal opens inside the Admin Portal. The default landing page is Lucky Draw History.

Note: Operator access to the Ops Portal requires Admin Portal permissions configured by your tenant administrator. The Ops Portal also requires the VIO External API Key to be configured for the tenant — without it, the voucher / token pickers in the Create / Edit wizard cannot load and reward delivery will fail. See Registration Reward - VIO External API Key for how to save the key.

---

2. Member App Screen Overview

When Lucky Draw opens inside the Member App, the page typically shows:

UI element	Purpose
Back (top left of Member App shell, ← arrow)	Returns to the previous Member App screen (usually the Mini Apps grid).
Title (centred at top of Member App shell)	Displays Lucky Draw as the active Mini App name.
Refresh (top right of Member App shell, circular-arrows icon)	Reloads the Lucky Draw mini app inside the viewer and re-sends your latest VIO session tokens. Useful when the page is stuck or shows stale data.
My rewards button (top right of the spin area, gift-box icon)	Opens My rewards at /rewards to view tokens and vouchers you have won. Located on the purple draw card, not in the Member App shell.
Machine / spin area	A gashapon-style machine illustration filled with capsule balls; the SPIN button sits on the front of the machine, next to the dispenser slot.
Event title (small uppercase caption under the machine)	The current event title set in the Ops Portal.
Spin status line	Shows remaining attempts (for example Spins remaining for today: 2) when limits apply. Not displayed when the rule is Unlimited.
Countdown banner	Shows Ends in (active event) or Starts in (upcoming event) with days, hours, minutes, and seconds.
Terms & Conditions section	Auto-generated rules below the spin area (event period, attempt policy, stock availability).

Tip: Refresh vs Back — Refresh reloads only the embedded mini app (your spin state may reset to the initial loading state and your session token is re-applied). Back leaves Lucky Draw and returns to the Mini Apps grid.

Tip: Stay on the draw page while spinning. Switching between apps or browser tabs during a spin can disrupt animations and result feedback.

---

3. Member Experience - Lucky Draw

3.1 Page states

The Lucky Draw page renders one of three main states based on event configuration:

State A: No Lucky Draw Event

• Calendar-style icon, heading No Lucky Draw Event
• Message: There are no lucky draw events at this time.

This appears when no event is configured in the Ops Portal, or when the API returns no eligible event.

State B: Coming Soon (upcoming event)

• Hourglass icon, heading Coming Soon
• Lines: No lucky draw event now, / Next event will start at + scheduled start time
• Starts in countdown banner (days · hrs · min · sec)

The page automatically refreshes when the countdown reaches zero.

State C: Active draw

• Gashapon-style machine with capsule balls; the SPIN button sits on the front of the machine, next to the dispenser slot.
• My rewards gift-box button is overlaid on the top-right of the purple draw card.
• Event title appears as a small uppercase caption directly under the machine.
• Spin status line is shown only when the rule is Per Day or Entire Event.
• Grab the Prizes Now! banner shows the Ends in countdown (days, hrs, min, sec).
• TERMS & CONDITIONS section appears below the countdown card.

3.2 How to spin

How to use:

1. Open Lucky Draw from Mini programme in the Member App.
2. Review the event title, Ends in countdown, and Terms & Conditions below.
3. Check the Spin status line (when shown) for the remaining attempts for today or for the event.
4. Tap SPIN in the centre of the machine.
   • The machine animation plays for about 2 seconds.
   • The button shows a busy state — do not double-tap.
5. Wait for the result modal. The page also refreshes the spins remaining counter automatically.

SPIN button states

Button state	Meaning
Active (gradient)	Event is active and you still have attempts left.
Disabled	One of: event not active, No spins left, or session missing.
Spinning (with animation)	The system is processing your draw.

3.3 Outcomes after a spin

After a spin, the page opens a result modal:

Outcome	Modal content
Win — token	Title image Congratulations!, two overlapping token circles, prize name, message Hooray! You won {prize name}!, and a View Rewards button.
Win — voucher	Title image Congratulations!, a voucher card with image, voucher name and Valid until / Event ends date, message Hooray! You won {prize name}!, and a View Rewards button.
No win	A neutral result message; you may try again later if rules allow.
Error	Title (for example Prize delivery failed, Event ended, No spins left, Out of stock) plus a short hint. The OK button closes the modal.

Note: When you see Prize delivery failed, your spin attempt is not consumed — you can try again. Other error states such as Event ended or Out of stock mean no more spins are accepted.

3.4 Terms & conditions

The TERMS & CONDITIONS section (heading shown in all caps) appears below the countdown card. Items are rendered as a numbered list (1., 2., 3., …) and are generated from the event configuration.

Typical items include:

1. Event period — for example: Event period: May 5, 2026, 03:35 PM to Sep 30, 2026, 03:31 PM.
2. Participation limit — one of:
   • You can spin as many times as you like during this event. (Unlimited)
   • Each user can spin up to N times per day. (Per Day)
   • Each user can spin up to N times for the entire event. (Entire Event)
3. Remaining attempts (only when Per Day / Entire Event apply) — You currently have N spin(s) left today. / ...left for this event.
4. Stock note — Prizes are subject to availability while stocks last.

Tip: Wording is generated from your event settings. Adjust Participation Limit in the Ops Portal if you need different rules.

Note: The bottom of the Terms list may be partially covered by the Member App's bottom navigation bar — scroll the inner content to read the last items.

3.5 Member-facing checklist (support macro)

1. Confirm you opened the correct tenant Member App.
2. Confirm the current date/time is inside the event window for active draws.
3. If No spins left, wait until the next eligibility window (next day or next event).
4. If a reward is missing, open My rewards (gift-box button) before contacting support.

---

4. Member Experience - My Rewards

The My Rewards page lists the tokens and vouchers you have won across Lucky Draw events. It opens from the gift-box button at the top-right of the draw page (or directly at /rewards).

4.1 What you see

• Back chevron (top-left): returns to the Lucky Draw page.
• My Rewards title.
• Reward list sorted by most recent first, each row showing:
  • Reward icon (voucher illustration or token circle)
  • Reward name
  • Date / time received
  • Quantity badge (+1 for a voucher, +N for tokens based on Tokens per User)
• Empty state (no rewards yet): gift icon, message You haven't won any rewards yet. and a Try Lucky Draw button.

4.2 How to use

1. Tap the gift-box button at the top-right of the Lucky Draw page.
2. Scroll the reward list; newest items appear at the top.
3. Tap a voucher row to jump straight into the Member App voucher detail page (/voucher/:userVoucherId).
   • This opens outside the Mini App iframe so the Member App can show the voucher properly.
   • If a voucher card cannot resolve a Member App URL, an inline hint such as Voucher link is not available appears for a few seconds. Token rows are informational and not tappable.
4. Use the Back chevron to return to the draw page.

Tip: Tokens that you win are delivered to your VIO wallet — also visible from Home -> Balance and Transaction History in the Member App.

---

5. Ops Portal - Lucky Draw History

The Ops Portal opens by default on the Lucky Draw History page at /.

5.1 Page layout

Section	Content
Title	Lucky Draw History — Manage and review all lottery events
+ Create Lucky Draw (top right)	Opens the Create Lucky Draw wizard. Disabled when an unpublished (Not Launched) event already exists — only one unpublished event is allowed at a time.
Search input (placeholder Search by event title…)	Filters the events table by title (press Enter to search).
Events table	One row per event with the columns listed below.
Empty state	When no events exist, a No Lucky Draw Events card invites you to Create your first lucky draw event.

Events table columns

Column	Description
Event ID	Backend identifier for the event.
Event	The event title set in step 1 of the wizard.
Created	Date and time when the event was created.
Starts	Scheduled start date and time.
Ends	Scheduled end date and time.
Duration	Compact span (for example 3d · 5h · 12m).
Status	Badge: In Progress (green), Not Launched (blue), or Ended (gray).
Actions	Edit (hidden when Ended) and Dashboard (becomes View when Ended).

5.2 How to use

How to use:

1. Open the Admin Portal -> Mini Apps -> Lucky Draw.
2. Use the Search input at the top of the list (placeholder Search by event title…) and press Enter to filter.
3. Click + Create Lucky Draw to start a new event (see Section 6).
4. On an event row:
   • Click Edit to modify an event that has not Ended.
   • Click Dashboard to open the event metrics (see Section 7); on Ended events the button is labelled View.
5. Watch the Status badge to understand the event lifecycle:
   • Not Launched — scheduled but not yet started.
   • In Progress — currently active.
   • Ended — past end time.

Warning: Only one Not Launched event can exist at a time. The + Create Lucky Draw button is disabled (with a tooltip) until you launch or remove the existing unpublished event.

---

6. Ops Portal - Create / Edit Lucky Draw

Both Create and Edit use the same 4-step wizard. The page title becomes Create Lucky Draw, Edit Lucky Draw, or View Lucky Draw (read-only when an event has Ended).

Stepper:

1. Basic Settings
2. Prize Configuration
3. Rules
4. Confirm & Create (becomes Confirm & Update in edit mode)

6.1 Step 1 — Basic Settings

How to use:

1. Event Title (required): up to 30 characters; the inline counter shows N/30.
2. Start Date & Time (required): future date/time. Validation rejects past times unless you are editing an already-started event.
3. End Date & Time (required): must be strictly after start. The form auto-bumps end to start + 1 hour when needed.
4. Show Lottery Entry After End (toggle):
   • On — members can still open the draw entry after the event ends (for example to view rules or history).
   • Off — the draw entry is hidden after end.

Inline validation banners

Banner	When it appears
Start time cannot be in the past	Start is set to a past time (only for new or not-yet-started events).
End time cannot be in the past	End is set to a past time.
The end time must be after the start time.	End is earlier than or equal to start.
Event time overlaps with existing event: {title}	Your time window overlaps another tenant event.

Note: Start time is locked for events that were already past their start time when loaded (the field becomes non-editable to prevent retroactive changes that affect members).

6.2 Step 2 — Prize Configuration

The prize table lists prizes that will appear on the wheel. The Total probability indicator at the top of the section must equal 100% before you can submit.

How to use:

1. Click + Add Prize to open the Add Prize modal.
2. Prize Type (radio): Token or Voucher.
3. Token:
   • Pick from the tenant's tokens (select dropdown). Tokens with no tenant balance are disabled.
   • Set Total Token Quantity (Stock) — capped by your token balance.
   • Set Tokens per User — the amount each winner receives.
4. Voucher:
   • Click Select voucher to open the voucher picker. Use the Search input (placeholder Search by voucher name…) to find a voucher.
   • Disabled vouchers show a reason: Already selected, Out of stock, or Has per-user claim limit.
   • Set Stock. The form caps stock by the voucher's remaining campaign quantity and warns when the value exceeds availability.
5. Auto Restock (toggle): when On, configure:
   • Restock Quantity (must be > 0)
   • Threshold
   • When to restock: Immediately when at/below threshold, At most once per hour, ...per day, ...per week
   • Max Total Restock (0 = unlimited)
6. Probability (%) is set per row in the prize table (after the prize has been added). The summary line shows Balanced when total equals 100%.
7. Use Edit / Delete / Restore in the Actions column to manage individual prize rows; deleted-from-wheel prizes are displayed with an Off wheel badge.

Validation rules

Rule	Behaviour
At least one active prize on the wheel	Otherwise the Next button shows a tooltip At least one active prize must be on the wheel.
Probability > 0% for every active prize	Otherwise Every active prize must have a probability > 0%.
Total probability = 100% (±0.1%)	Otherwise the summary shows Over by N% or Remaining: N%.
Token stock ≤ tenant token balance	Stock is capped automatically; an inline message states the cap.
Voucher stock ≤ campaign remaining quantity	Warning appears: Insufficient voucher quantity. Voucher campaign available quantity is N; please reduce the prize stock.

6.3 Step 3 — Rules

Configure how often a single member can spin.

Option	Behaviour
Unlimited	No participation limit.
Per Day	Each user can spin up to N times per day. Enter the value in the inline number field.
Entire Event	Each user can spin up to N times for the whole event. Enter the value in the inline number field.

Note: Per Day and Entire Event require the value to be >= 1, otherwise the wizard shows Participation limit must be >= 1.

6.4 Step 4 — Confirm & Create / Update

The final step lists everything for review before saving:

• Basic settings — Event title, Start, End, Duration, Show after end.
• Prizes — Prize Name, Type badge, Stock (with Remaining in edit mode), Auto Restock summary, Probability.
• Rules — Participation limit summary.

Actions:

• Previous — go back to make changes.
• Create Lucky Draw (create mode) / Update Lucky Draw (edit mode) — saves the event.
  • On click during edit, a Save changes? confirmation modal asks you to confirm the update.

Warning: When you click Update Lucky Draw on an active event, changes apply immediately to members. Adjust dates, prizes, or limits with care so members already participating are not impacted unfairly.

If you click the back chevron with unsaved changes, the wizard opens a Leave creation? / Leave without saving? dialog with Keep editing and Leave options.

---

7. Ops Portal - Event Dashboard

Open Dashboard (or View for an Ended event) on a row in Lucky Draw History to inspect performance.

7.1 Page layout

Section	Content
Period filter (top)	Buttons: Today, This Week, This Month, All Time — switches the metric window.
Stats grid	Two KPI cards: Total Participants and Unique Users.
Prize Claim Status	Table per prize: Prize Name, Type badge, Status (Active / Off wheel), Total stock, Remaining, Claimed.
Event details	Title, Status badge, Start time, End time, Duration, Prizes summary (on-wheel + archived), Show after end.
Back chevron (top left)	Returns to Lucky Draw History.
Error banner	Shows Failed to load dashboard if the API call fails; use Back to retry from history.

Note: Total stock on the dashboard reflects the original stock minus everything claimed so far, plus any restocked amount. Remaining is the current live stock available for new spins.

7.2 How to use

How to use:

1. From Lucky Draw History, click Dashboard (or View for an Ended event) on the event row.
2. Choose a Period at the top to reload metrics for that window.
3. Review the Stats grid — Total Participants vs Unique Users tells you how many people participated and how many distinct accounts engaged.
4. Scroll to Prize Claim Status to verify each prize:
   • Confirm Remaining is healthy for the rest of the campaign.
   • Off wheel rows are archived prizes (no longer eligible to be drawn but still counted historically).
5. Use Event details to double-check the schedule and the Show after end setting before announcing or closing a campaign.
6. Use Back to history (back chevron) to return to the events list.

---

8. Operational Workflows

8.1 Launch a new draw

1. Create the event in the Ops Portal (Sections 6.1–6.4).
2. Verify the dates, prizes, and participation limits in Confirm & Create.
3. Open the Member App with a test account and tap the Lucky Draw tile.
4. Spin once with a test account and confirm:
   • The result modal displays the expected prize type.
   • The prize appears in My Rewards.
   • Token balance / voucher list in the Member App reflects the win.
5. Communicate the campaign to your members (push notification, news article, marketing page).

8.2 Edit a live event

Warning: Editing an In Progress event can affect members who already participated. Avoid changing dates or prize structure mid-campaign unless absolutely necessary.

1. Open Lucky Draw History and click Edit on the row.
2. Make minimal, well-understood changes (for example, restock a prize).
3. Step through to Confirm & Update, confirm the Save changes? dialog.
4. Verify the change immediately from the Member App.

8.3 End-of-event

1. Let the event end naturally at its scheduled time, or pause delivery upstream if required.
2. In Lucky Draw History, the row Status becomes Ended and Edit is hidden.
3. Open View (dashboard) to capture final metrics for finance / compliance reporting.
4. Use the Show Lottery Entry After End setting (in Basic Settings) if you want members to keep accessing the draw entry for rules or history review.

---

9. Troubleshooting

For members

Symptom	What to check
Page blank / endless spinner	Tap Refresh (circular-arrows icon, top right of the Member App shell) to reload the mini app. If still blank, check network connection and reopen Lucky Draw from Mini programmes.
Page shows stale event or old countdown	Tap Refresh to reload the mini app inside the viewer.
Sees No Lucky Draw Event	No event is configured, or the event is outside its window.
Sees Coming Soon	The event is scheduled but not started yet.
SPIN button disabled	Event not active, No spins left, or session missing — tap Refresh, or reopen Lucky Draw from the Member App.
Prize delivery failed modal	Reward backend issue — the spin is not consumed; try again or contact support.
Reward not visible	Open My Rewards (gift-box icon) first. Tokens also show in Home -> Balance and Transaction History.

For operators

Symptom	What to check
Cannot click + Create Lucky Draw	A Not Launched event already exists. Launch or remove it first.
Next button on Step 2 disabled	At least one active prize required and Total probability must equal 100%.
Voucher stuck as Has per-user claim limit	The voucher has a per-user claim limit configured in the VIO voucher settings; create a separate voucher (or set it to unlimited per user) for the campaign.
Event time overlaps with existing event	Adjust Start / End in Basic Settings, or end the overlapping event.
Entries saved but rewards not delivered	Check the dashboard Prize Claim Status, the tenant token balance, and the VIO External API key/configuration.

---

10. Business Rules & Notes

Topic	Guidance
Session	Members should open Lucky Draw from the Member App so the VIO session is passed correctly to the Mini App.
Stock model	Prize stock is the original stock minus what has been claimed, plus any restocked amount. Auto-restock keeps stock alive up to the maximum restock cap configured for the prize.
Probability	Active prizes must sum to exactly 100% (±0.1%). Probabilities are independent across on-wheel prizes only — archived (Off wheel) prizes never participate in the draw.
Participation limit	Per Day uses the platform's calendar day boundary. Entire Event is cumulative for the duration of the event.
Reward delivery	Rewards are issued via the VIO External API. If VIO_SEND_FAILED is reported, the member's spin is not counted and may be retried.
Editing	Edits to live events take effect immediately on the Member App once Update Lucky Draw is confirmed.
Compliance	Always state event period and participation rules clearly. Surface them in the campaign description and rely on the Terms & Conditions section auto-generated by the draw page.

---

See also Mini Apps overview, Claim Mini App, Marketing Mini App, Registration Reward Mini App, and Member App - Home.