Referral Mini App - User Guide

The Referral Mini App lets each existing member invite friends with a personal 6-character code. When a friend registers using that code, both sides receive a token reward from the same campaign. Members handle invites in the Member App; operators choose the reward token, amounts, and daily cap from the Ops Portal.

Note: Members access the Mini App through the Referral tile in the Member App. Operators access the Referral Ops Portal from the Admin Portal.

---

Table of Contents

1. How to Access
2. Member Experience
3. Ops Portal - Referral Rewards
4. Ops Portal - Invite History
5. Business Rules & Notes

---

1. How to Access

For Members

1. Open the VIO Member App and sign in.
2. On Home, tap the Referral tile in the Mini Apps section.
3. The Referral home page opens with your personal invite code and reward summary. No separate login is required — your VIO session is reused.

Note: If the session is missing or expired, an authentication warning appears. You can still browse the page, but copying the code and viewing history may not work until you sign in again.

For Administrators (Ops Portal)

1. Open the Admin Portal and sign in with an account that belongs to the tenant.
2. From Dashboard or Mini Apps, open the Referral entry. The Ops Portal loads inside the Admin Portal frame.
3. The portal has a top bar with the Referral Ops brand on the left and an Invite history link on the right.
4. The default landing page is Referral rewards, where the reward token, amounts, daily cap, and the on / off switch live.

Note: Operator access requires Admin Portal permissions assigned by your tenant administrator. The Ops Portal also needs the VIO External API Key to be saved for the tenant — without it, token rewards cannot be delivered. See Section 3.2.

---

2. Member Experience

The member side is a short, two-page app: a home page with the invite code, the reward amounts, and today's progress, plus a history page that lists every successful invite.

---

2.1 Top Navigation

Every member page sits below the same top bar. It stays visible while scrolling so members always know where they are.

Element	Purpose
Referral (brand)	Brand label on the left. Tapping it returns to the Home page.
Home	Tab on the right. Highlighted when the member is on the home page. Tapping it loads the invite code, reward summary, and daily progress.
History	Tab on the right. Highlighted when the member is on the history page. Tapping it opens the personal invite history (see §2.6).

Note: The active tab is shown with a highlighted pill style; the inactive tab is muted. The top bar is part of the Mini App itself — the VIO Member App's own header (with back button and tenant info) sits above it.

---

2.2 Page States

The page renders one of these states depending on tenant configuration:

State	When it appears	What members see
Loading	Right after opening the page	A skeleton placeholder while the page fetches your info.
Disabled	The tenant has Referral rewards switched off	Red banner: Referral program is currently disabled. Invites may still register, but rewards will not be issued. The code is still shown and copyable, but no rewards will be sent.
No tenant	The signed-in account has no tenant	Yellow banner: No tenant on your account. Open this app from your organization context. The page is read-only.
Active	Configured and enabled	Full hero, invite code card, daily progress, and history button.
Error	Page failed to load	Red error banner with a Retry button.

---

2.3 Hero — Reward Summary

The top card shows what each side gets:

• Headline: Invite a friend and get {Inviter amount} {token}
• Sub-line: When your friend registers with your code, they get {Invitee amount} {token}

The token label is whatever the operator selected (token symbol or token name). If amounts have not been configured, the page shows a dash (—) instead of a number.

---

2.4 Invite Code Card

The middle card carries the actual invite code:

• Code: A 6-character code in upper case. The character set avoids easily-confused characters (no 0, O, 1, I, L).
• Copy button: Tap Copy to copy the code to the clipboard. The label briefly changes to Copied for 2 seconds as confirmation.
• Hint: Share this code with friends. Matching ignores letter case.

Tip: Tell friends to type or paste the code during their VIO registration. Lowercase and uppercase are treated the same.

---

2.5 Daily Progress

Below the code card, members see today's count of successful invites:

• Label: Daily successful invites
• Value: today / max when a daily cap is set (for example 3 / 5), or just today followed by (no daily cap) when the operator set the cap to 0.

This counter only counts successful invites for today, in the tenant's reporting time zone. Invites that were skipped because the daily cap was reached are listed on the history page but do not increase this number.

---

2.6 Invite History (Member)

Tapping Invite history opens a list of every successful invite tied to the member:

Field	Description
Friend	The friend's display name (or user ID if the name is not available).
Your reward	The token reward the inviter received for that invite.
Time	When the invite was recorded, formatted in the device's local time.

States on this page:

State	What it shows
Loading	Skeleton placeholder.
Empty	A card with the heading No invites yet and a hint When someone registers with your code and rewards are recorded, entries will appear here.
List	One card per invite, newest first.
No tenant	Yellow banner No tenant on your account.

Buttons:

• ← Back — returns to the Referral home page.
• Refresh — re-fetches the list (handy if a friend just registered).

---

3. Ops Portal - Referral Rewards

Top Navigation

Every Ops Portal page sits below the same top bar. It stays in place while the page below changes.

Element	Purpose
Referral Ops (brand)	Plain text label on the left. It is not a link — clicking it does nothing.
Invite history	Link on the right. Highlighted when the Invite history page is open. Clicking it switches the body to the Invite history page (see Section 4).

Note: There is no separate Referral rewards link in the top bar — that page is the default landing view. To return to it from Invite history, click anywhere on the Referral Ops brand area to reload the portal, or use your browser's back button. (The brand text itself is non-clickable, but the portal's default route opens Referral rewards.)

---

Layout

The Referral rewards page is the default landing view. It is organized into three stacked cards that should be completed in order:

1. Referral rewards enabled — the master on / off switch.
2. VIO External API key — required before any token list or reward delivery works.
3. Reward token and amounts — choose the token, amounts, and daily cap.

Note: If your VIO user has no tenant, the page shows a yellow banner Your VIO user has no tenantId. Open this page from the VIO ops context with a tenant. All controls are disabled until the tenant context is restored.

---

3.1 Referral Rewards Enabled

This is the master switch that decides whether rewards are sent when a new member registers with someone's invite code.

Control	Purpose
Referral rewards enabled	On / off switch. The label next to it reads Enabled, Disabled, or Updating… while saving.

What On / Off do

• Enabled — every successful invite triggers a token reward for both the inviter and the invitee, subject to the daily cap. Before the switch can be turned on, you must already have (a) a saved API key, and (b) a complete reward setup (token + non-zero inviter / invitee amounts + valid daily cap). Otherwise the server rejects it with an error banner.
• Disabled — invites can still be registered (so people are not blocked from signing up), but no token rewards are sent. The Member App shows a red banner explaining this to inviters.

How to use:

Step 1: Toggle the switch

• Click the switch to flip it. The label momentarily shows Updating… while the request is in flight.

Step 2: Confirm the result

• After a successful save, the label settles on Enabled or Disabled.
• If the server rejects the change (missing API key or missing reward fields), a red error banner appears at the top of the page and the switch goes back to its previous position.

Note: Switching to Disabled does not undo rewards that were already sent. It only stops future invites from being rewarded.

---

3.2 VIO External API Key

The Referral mini-app needs a VIO External API key to (a) load the tenant's token list and (b) actually send token rewards to members. Each tenant stores one key.

Control	Purpose
Status block	Shows Key saved with a masked value like ****abcd and the last update time, or No API key saved yet. if empty.
API key input	A password-style input. Placeholder text changes based on whether a key is already saved.
Save API key	Saves the pasted value as the tenant's key. Disabled until the input is non-empty.
Remove saved key	Clears the saved key. Disabled when no key is saved or when Referral rewards are still on.

How to use:

Step 1: Get the key

• Get the tenant's API key from the API Keys area in the VIO Admin Portal. Each tenant has its own key.

Step 2: Paste and save

• Paste the value into the input. The placeholder reads Paste your VIO External API key when empty, or Paste only to replace the saved key when one is already saved.
• Click Save API key. The button reads Saving… during the request.
• After a successful save, the status block updates to Key saved with a masked value and timestamp. The token list in the third card reloads automatically.

Step 3: Replace or remove (optional)

• Replace: paste a new key over the old one and click Save API key again. The previous key is overwritten.
• Remove: first switch Referral rewards off (see §3.1), then click Remove saved key and confirm the browser prompt Remove the saved API key for this tenant? The token list and reward calls will stop until you save a new key. The status returns to No API key saved yet. and the token list clears.

Note: The key is stored on the server, not in the browser. Only operators with Admin Portal access can update it. Always rotate keys here — do not paste them into other portals or share them through unsecured channels.

---

3.3 Reward Token and Amounts

This card decides which token is sent and how much each side receives.

Control	Purpose
Reward token	Drop-down listing tokens loaded from VIO. Each option shows Name (Symbol) — Available: {balance}. Tokens with zero available balance are greyed out as Unavailable.
Available balance	Sub-line under the drop-down showing the selected token's sendable balance.
Inviter amount	Number input for the amount the inviter receives per successful invite. Must be > 0.
Invitee amount	Number input for the amount the invitee receives. Must be > 0.
Max rewarded invites per day	Integer input for the daily cap per inviter. 0 means no cap.
Save reward settings	Saves all four fields above as one bundle. Disabled when nothing has changed.

How to use:

Step 1: Pick a token

• Open the Reward token drop-down. If the list is empty, save the API key first — it will populate automatically.
• Pick a token. The Available balance line confirms the sendable balance for that token. Greyed-out tokens cannot be selected.

Step 2: Set the amounts and daily cap

• Enter a positive number in Inviter amount and another in Invitee amount.
• Set Max rewarded invites per day — for example 5 to reward up to 5 invites per inviter per day, or 0 to remove the cap.

Step 3: Save

• Click Save reward settings. The button reads Saving… during the request.
• After a successful save, the button becomes disabled until you make another change. The new values take effect for future invites only.

Note: Once the daily cap is reached for an inviter, further successful invites that day still register and appear in Invite history, but the reward is skipped with a Daily reward limit reached status. The cap resets at midnight in the tenant's reporting time zone.

---

4. Ops Portal - Invite History

The Invite history tab shows every invite event recorded for the tenant, regardless of whether the reward was sent, skipped, or failed.

---

4.1 Records Card

Control	Purpose
Total summary	Sub-line Total {N} (showing {M} on this page) — reflects the latest fetch.
Refresh	Reloads the list. Reads Refreshing… while in flight.

---

4.2 Table

Each row represents one invite event. The most recent event is at the top.

Column	What it means
Inviter	The inviter's display name, falling back to user ID when name is unavailable.
Invitee	The invitee's display name, falling back to user ID.
Time	When the invite was recorded, in the browser's local time.
Inviter reward send	Per-leg delivery status of the inviter's token — Sent, Failed ({reason}), Skipped (rate limit), Skipped (not configured), or a legacy fallback for older rows.
Invitee reward send	Same as above, for the invitee's token.
Tokens (Inviter / Invitee)	Plain-language summary like Inviter: [amount] [token name] / Invitee: [amount] [token name].
Status	Overall badge for the row — see §4.3.

If there are no records yet, the table shows: No records yet. Rows appear when the referral flow writes invite events.

---

4.3 Status Badges

The right-most column carries one badge per row:

Badge	Meaning
Success (green)	Both legs of the reward were sent.
Daily reward limit reached (yellow)	The invitee was registered, but the inviter's daily cap had already been reached, so no token reward was sent.
Send failed (red)	The reward send attempt failed for at least one leg. Use the per-leg columns to see the reason (e.g. Failed (Out of stock), Failed (Invalid key)).
Other	A short text fallback for legacy statuses that do not match the three above.

Note: This page does not have a resend button. To recover from a failure, fix the root cause (key, balance, or settings) and ask the inviter to invite again, or have a tenant administrator review the records.

---

5. Business Rules & Notes

Code Generation

• Each member is automatically assigned one 6-character invite code the first time they open the Mini App. The same code is reused for every invite.
• The code uses a restricted character set (digits 2–9 and uppercase letters, excluding 0, O, 1, I, L) to reduce confusion when read out loud or transcribed.
• Validation is case-insensitive — abcd23 is treated the same as ABCD23.

One Code, Many Invites

• An invite code can be used by many different friends. Each successful registration with the code creates one row in the history.
• A friend can use only one invite code at registration time.

Daily Cap

• The cap is per inviter, per calendar day (in the tenant's reporting time zone).
• When the cap is reached, further invites that day still register the friend, but the inviter / invitee token rewards are skipped with a Daily reward limit reached status.
• Setting the cap to 0 removes the limit. There is no upper limit on the cap value, but high numbers can affect the token balance quickly — keep an eye on the Available balance line in §3.3.

When Rewards Are Sent

• Both rewards (inviter + invitee) are sent at the moment a friend completes VIO registration with the code.
• If the Referral rewards switch is off, the registration is still allowed and the row is written to history, but neither leg is sent.

Tenant Scope

• Reward token, amounts, daily cap, and API key are configured per tenant. Different brands can have completely different setups.

Access Control

Role	Member App	Ops Portal
Regular member	Can see own code, copy it, and view own invite history.	No access.
Tenant admin	Same as a regular member.	Full access (Referral rewards, Invite history).

---

See also: Mini Apps overview, Daily Check-In Mini App, Registration Reward Mini App.