Minigame platform: product overview

For the product owner. No technical knowledge needed. Use it to explain the product to agencies and brands, set up new customers, run demos, and answer what's possible, what's included, and what we can't promise yet.Matches branch feat/consolidate as of 2026-11-10. Vietnamese labels in bold are what admins see on screen.

---

1. What it is

A white-label promotional minigame. People open a link on their phone, play a short game, and win a prize from the brand's stock. The brand (or the agency running it) manages everything from an admin site at /admin.

• One deployment = one agency. Each agency gets its own website deployment, its own database and its own image folder. Agencies never see each other's data.
• Players don't log in. They play, then enter their details to claim the prize.
• All admin screens are in Vietnamese.

2. Who's who: three tiers

Role	Shown as	Who	What they do
Owner	Nhà cung cấp	Us, the platform operator	Everything. Decides what each agency may use and resell, sets the agency's license, manages house ads and affiliate links, turns multi-client mode on. Never locked out by a license.
Agency	Agency	A reseller, or us when we sell directly	Manages its clients: creates them, sets each client's license and quotas, grants them features, invites their admins, and can "step in" to any client's campaign. Can't edit its own license.
Admin	Admin	A client's (brand's) user	Runs the client's campaigns: prizes, look and feel, rules, surveys, ads. Sees only its own client.
Player	n/a	The public	Plays, claims the prize, answers the survey.

How the sales cases map onto this

• Selling directly to brands: we are both owner and agency. Each brand is a client.
• Selling through a partner agency: we are the owner only. The partner is the agency.
• One campaign vs many: just a quota on the client's license.

Clients and campaigns

• A client is a customer of the agency (a brand). Client default always exists.
• A campaign is one game setup that players see. Each has a name and a link: the root campaign plays at /, every other one at /c/{slug}.
• Campaigns have a status: scheduled (shows a coming soon page with a countdown until the start date), live, or ended (shows a closed screen). A campaign can be archived and restored, and its link can be changed until the first player arrives.
• Switcher (sidebar): owner and agency pick a client and then a campaign. A client admin only sees its own campaigns. Every other admin page edits the selected campaign.

Single-client (legacy) mode

By default a deployment is in the old single-brand mode: one campaign, no client UI, and anyone who signs in is an admin. The owner can switch on Nhiều khách hàng (multi-client mode). Only invited people can then get into the admin. Only the owner can switch it back, and only while no extra client or campaign exists. Check with the dev team before turning it on for a live site.

Inviting people

The owner invites agency staff and the agency invites client admins. No email is sent by us. Tell the person to open /login, choose Tạo tài khoản, and sign up with the invited email. They confirm the verification email Firebase sends, and their role is created. An email that wasn't invited is rejected.

3. The games

Game	Label	Notes
Scratch card	Thẻ cào	The player scratches the cover. Admins set how much has to be scratched before it reveals (1–100%) and the brush size.
Wheel	Vòng quay	The wheel shows prizes as text labels and always lands on the prize the system picked.
Mystery bag	Túi mù	The player picks a bag from a grid (3–12 bags, 2–4 columns) and tears it open. Colours, bag image, label text, copy and tear distance are editable. Paid feature.

Admins choose the active game in Quản lý trò chơi (/admin). All three share the same screens, prizes, rules and look.

Queued, not built: making each game type something the owner and agency can grant to clients, like other features.

4. The player journey

Default journey: intro → player info → (pre-roll video) → rules → play → result → wallet (winners only) → (survey).

The wallet shows the prize the player won, with an optional countdown (0–1440 minutes, 0 hides it) so they show it at the counter in time.

Custom journeys (feature Kịch bản trò chơi, page Kịch bản): reorder or remove screens and show screens only under conditions: won or lost, won a particular prize, first visit or returning, during a lucky time slot, mobile or desktop. This only arranges our existing screens. Agencies can't add their own code or pages.

Without customisation, the journey comes from the template (section 7).

Look of the game: the campaign background (image, colour or gradient) fills the whole screen on every device, with no card around the game. A slim see-through header (brand, game name, trophy) and a quiet footer (footer text plus the small "powered by" logo) frame it. Admins edit the header and footer in the campaign editor.

5. Features and who controls them

Features work on two levels:

1. Entitlement: the owner entitles an agency, and the agency entitles its clients, either permanently or for a date range (section 6). A client only ever gets what the agency itself has.
2. Switch: the admin turns each entitled feature on or off on the Tính năng page.

A feature works only when both are on. Owner-only features skip step 2.

Feature (on-screen label)	What it does	On by default*	Package
Danh sách trúng thưởng	Trophy button with the winners list	✅	Cơ bản
Giới hạn lượt chơi	One play per browser	✅	Cơ bản
Cảnh báo lượt cuối	"Bạn còn 1 lượt chơi duy nhất!" notice	✅	Cơ bản
Chi nhánh	The player picks a branch in the info form	✅	Cơ bản
Người giới thiệu	Optional "referred by" name field	✅	Cơ bản
Nhập file Excel	Add winners in bulk from .xlsx (Excel export is always available)	✅	Cơ bản
Khung giờ may mắn	Better odds for special prizes during set time slots	—	Nâng cao
Phần thưởng theo lượt	Give a chosen prize every N plays	—	Nâng cao
Khảo sát	Survey after the prize, plus question and response pages	—	Nâng cao
Video quảng cáo	Video before the game, skippable after N seconds	—	Nâng cao
Túi mù	The Mystery Bag game	—	Nâng cao
Kịch bản trò chơi	The custom journey editor	—	Nâng cao
Gói quảng cáo riêng (premium)	The brand's own ads and product catalogue (section 8)	—	Premium quảng cáo
Quảng cáo hệ thống	Our house ads fill ad slots when the client isn't premium	—	—
Nhập mẫu giao diện	Import template files	—	—
Thống kê	Analytics page. Permanent grant only, not by date range.	—	—

* How a deployment behaves before anyone has opened the Tính năng page. It matches the original gym3 product.

Settings every client has: brand name, logo, sound on or off, prizes and stock, and the look (section 7).

"Client manages" switches: per client, the agency decides whether the brand edits its own prizes, look and journey itself (the brand sees edit buttons) or the agency does it all (the brand gets a read-only view). The agency sets this per client.

6. Licensing, quotas and packages

These controls are visible only to the owner and agency, and are enforced on the server, so they can't be bypassed from the browser.

Two license levels

• The owner sets the agency's license: window, expiry mode, maximum number of clients, and total campaign limit (empty = unlimited).
• The agency sets each client's license: window, expiry mode, and maximum campaigns (a new client gets 1).
• What a client can use is the overlap of both licenses and both sets of grants. When the agency's license ends, every client stops with it.
• Client admins see their license read-only, with a banner in the last 7 days.

License window and expiry mode

A start date and an end date. No dates means unlimited. Before the start or after the end, players see a "closed" screen. What happens to admins is set per customer, to match what was negotiated:

Mode	Label	Players	Admin
Lock everything	Khóa toàn bộ	Closed	Locked out
Read-only admin	Admin chỉ xem	Closed	Can view and export, can't change
Lock players only	Chỉ khóa người chơi	Closed	Full access (to prepare the next campaign)

The owner is never locked out. The agency can always step in to a client whose license has expired.

Play quota

A license can cap the total plays over its period. Reaching the cap starts a grace period (set per license), after which the level locks like an expired window. There's no monthly reset for now.

Campaign quota

The agency page shows Đã dùng n/max chương trình. The root campaign counts as #1 of client default. Its first extra campaign needs the Nhiều chương trình grant on both the agency and the client. Other clients' first campaign needs no grant.

Packages and time-limited grants

• A grant gives features for a date range, for example "premium ads for Nov–Dec". Make it from a package in one click or feature by feature. Each feature can have its own dates.
• Packages: Cơ bản, Nâng cao (basic + lucky times, forced prize, survey, video ad, mystery bag, journey editor), Premium quảng cáo.

  The package contents are placeholders. Tell the dev team the real packages and they'll be updated. Editing a package later doesn't change grants already given.

7. Look and feel: templates (page Giao diện)

The look comes from a template: a designer-made file with colours, fonts, background, confetti, default copy, the default journey per game, and the default ad pattern.

• Built-in templates: Default (Impakt) for new deployments, and Gym3 (navy and gold). Existing gym3 agencies stay on Gym3 automatically.
• Customisable: colours, fonts, background, confetti, copy, and a fallback image for broken images. One game can get a different look.
• Preview: full-screen in phone, tablet or desktop size. Previews never save data or use up prizes.
• Template versions: when a designer ships a new version, the admin sees an update, reviews it and updates without losing its own edits.
• Import and export: any admin can export their look as a file. Importing needs the owner, or the Nhập mẫu giao diện feature. A bad file is rejected, never half-applied.
• A template can't switch features on or add code.
• The admin site itself is neutral (not gold and navy), so agencies can resell it, with Light, Dark and System themes. It works on tablets.

Promise to agencies: switching templates changes the look, not how the game works. Saved settings, prizes and winners are never touched until an admin saves.

8. Prizes and the prize library

• Prizes: name, image, stock and a weight (relative odds). A slice can be a "no prize" outcome. A prize with no stock left can't be won. Stock is reserved safely when many people play at once.
• Kho giải thưởng (prize library): each brand keeps one library of prizes and their stock. When a prize is assigned to a campaign, that campaign holds a share of the stock. When the campaign ends (end date, archive or manual end), the unused share returns to the library. A log records every movement and is readable by the agency, the brand and the owner.
• Who edits it: the agency always can. A per-client switch lets the brand manage it itself.
• Khung giờ may mắn: time slots in which a special prize is won with a set probability.
• Phần thưởng theo lượt: every N-th play wins a chosen prize.
• Winners and rewards (Quản lý phần thưởng): everyone who won, with their details, exportable to Excel.
• Survey: the client writes its own questions and reads the responses.

9. Ads, store links and analytics

Brand ads (premium, page Quảng cáo)

With Gói quảng cáo riêng, a client can place a banner on each screen, a full-screen timed ad (1–30 seconds), and a product catalogue in the wallet. Each product links to one or more stores (Shopee, Lazada, TikTok Shop, Tiki or a website) and the player picks. Wide and square ads can be mixed into the catalogue.

House ads (ours)

With Quảng cáo hệ thống, our ads fill the slots of clients that haven't bought premium. Only the owner or agency (if granted) manages them.

Affiliate links

The owner or agency can replace a product's store link with a partner's affiliate link. The partner name is configurable. The brand enters its own link first and can see but not change an override. When the brand changes the original link, the override is flagged stale until it's updated or confirmed with "Xác nhận link vẫn đúng".

Analytics (page Thống kê)

Built to help brands earn money, not just count. It reports store-button clicks (by day in Vietnam time, product, store, affiliate vs own link), plus plays by hour and day, prize redemption, leads, referrers, survey answers and the funnel of the custom journey. Agencies can compare across their clients. Only real players are counted. Clicks and plays from a logged-in admin testing the game are ignored.

10. Demo environment

For showing the product to agencies and brands without risking real data. It runs as its own separate deployment, never on a customer's site.

• Sample agency (Agency mẫu): the demo site plays a ready-made agency with sample brands Mộc An Cosmetics (campaigns: ended, live, scheduled) and Trà Mây (agency-managed, license about to expire, trial play quota). Sample history is included so charts show real shapes.
• Tour logins: three fixed shared accounts (agency, Mộc An, Trà Mây) for the product owner only. Don't hand them out. In tour mode a banner says it's sample data and a Xem với vai trò switch moves between Agency and brand views without passwords.
• Prospect copies: for a specific prospect, create their own isolated copy with its own login. The "Kèm dữ liệu quảng cáo" option (on by default) adds sample ads. Copies can be reset (fresh sample data, same login), have their password reset, or be deleted.
• All of it is managed by the owner from the Bản demo page (sidebar, owner only).

Before a meeting: check the sample agency's "last refreshed" line and refresh it if it's old, so dates are recalculated from today. After a meeting: refresh the sample agency. Brands created during the tour are removed.

Suggested demo order: agency view (client list, switcher, analytics comparison) → Mộc An campaigns and statuses (ended / live / coming soon) → play the live campaign on a phone → analytics → rewards → ads and affiliate lock → look and journey → add a prize → Trà Mây to show the agency-managed (read-only) and expiring-license cases.

If something stalls: a creation, reset or delete that was interrupted shows a Tiếp tục (continue) button. Press it and it resumes. If an email is reported as already used but no copy is listed, the dev team must delete the leftover account in the database console.

11. Setting up a new agency (checklist)

1. Dev team: create the agency's database project, website deployment and image-upload settings.
2. Dev team: make the owner account, and the agency's staff accounts.
3. Owner → Nhà cung cấp: set the agency's license window, expiry mode, client and campaign limits, and the grants or package they bought.
4. Owner: if they're a multi-client agency, switch on Nhiều khách hàng.
5. Agency → Khách hàng: add a client, set its license and campaign quota, grant features, invite its admin.
6. Client admin → Quản lý trò chơi: choose the game, add the brand name, logo and prizes with stock.
7. Client admin → Giao diện: pick or adjust the template and check the phone preview.
8. Client admin → Tính năng: switch on the features they want.
9. Optional: survey, lucky times, journey, ads.
10. Play the game once on a real phone, then share the link.

12. What to be careful promising

Topic	Reality today
Player data privacy	⚠️ The security rules were deliberately loose so the game runs without logins. A lockdown is built in two phases: phase 1 is done, and phase 2, which actually closes off winners' details (name, phone, branch) and survey answers, is built later and only after phase 1 has been live on that site for at least a day. Until phase 2 is live on a customer's site, don't promise that player data is private or compliant (for example with Decree 13). Ask the dev team which phase a customer is on.
"One play per person"	The limit is per browser. A player who switches browser, uses private mode, or clears data can play again. Phone-number checks help but aren't a hard guarantee.
Single-client mode	Anyone who signs in is a full admin. Use multi-client mode when roles matter.
"Powered by"	Shows Gomini by default. A custom or hidden logo is a flag the owner grants an agency. The fallback order is agency → owner → built-in.
Journey editor preview	There's no live preview of a custom journey yet. Test with the full-screen preview or a real phone.
Packages	Placeholder contents (section 6).
Game types as entitlements	Not built yet (section 3).
Switcher polish	Known small gaps on tablets: a doubled switcher on some narrow-desktop pages, and a few small tap targets.

13. Decisions awaiting your confirmation

Decided during the build and waiting for a yes or no from the product side:

1. Analytics ignores logged-in admins, so testing doesn't inflate numbers.
2. Stale affiliate links stay stale until updated or confirmed.
3. Analytics can only be granted permanently.
4. Saving Giao diện keeps every value, even values identical to the template. This is safer for old data. The trade-off: if a later template version changes one, the client keeps its saved copy.
5. An unreadable or newer-version saved template blocks saving on Giao diện. There's no "replace anyway" for the owner yet.
6. Prize library: converting a prize to "no prize" keeps its remaining stock as the slice cap (unlimited only when it's 0) and asks to confirm. Settling a campaign counts winners of prizes merged into it.
7. Campaign end date at midnight replaces a game in progress with the closed screen.
8. New Vietnamese copy (for example Ẩn lại tên cũ, the PII-gate lines) hasn't been signed off by you.
9. Design calls: the see-through header and footer look heavy on Impakt's light flat colour, and the built-in powered-by logo needs a light variant for dark footers.