Marketing Mini App - User Guide

The Marketing Mini App lets operators build branded marketing pages (banners + linked vouchers / campaigns) and share them with members through a generated link or QR code. Operators create and manage pages in the Marketing Ops Portal.

Note: Each marketing page is a standalone PWA hosted at /marketing/{Marketing Page ID}. Members reach it through the link / QR code generated in the Ops Portal — typically shared via email, in-app push, social media, or printed material. If a member opens the link from inside the VIO Member App, it renders inside the Member App shell; otherwise it opens directly in the device browser. Operators access the Ops Portal from the Admin Portal and need the VIO External API Key configured for their tenant (see Registration Reward - VIO External API Key).

---

Table of Contents

1. How to Access
2. Member Experience - Marketing Page
3. Ops Portal - Marketing Page List
4. Ops Portal - Create / Edit Marketing Page
5. Operational Workflows
6. Troubleshooting
7. Business Rules & Notes

---

1. How to Access

Members — Open the marketing page link shared by the operator (email, in-app push, social, printed QR, etc.). The link follows the format {pwaBaseUrl}/marketing/{Marketing Page ID} and renders the marketing page directly. If the member opens the same link from inside the VIO Member App, it loads inside the Member App shell with the standard back / refresh controls.

Operators — Sign in to the Admin Portal and open Marketing from the Mini Apps section. The Ops Portal lands on Marketing Page at /marketing, which lists every marketing page configured for your tenant.

Tip: To generate the link for a page, open the Ops Portal, find the row, and click Download QR in the Actions column. The QR modal shows the Marketing Page Link plus a Copy link button and a Download QR Code button (see §3.2 Row actions).

---

2. Member Experience - Marketing Page

2.1 Page states

The marketing PWA renders one of the following states based on the URL and the page configuration:

State	When it appears	What members see
Loading	Page data is being fetched.	Centred spinner with Loading....
Configured marketing page	URL is /marketing/{id} and the page is published and unhidden.	Full layout (logo, banner carousel, slogan, voucher / campaign sections, Let's Discover More CTA).
No Marketing Page Configured	URL is / or has no page ID.	Heading No Marketing Page Configured, body This link does not include a marketing page ID. Please open a valid marketing page link from the campaign or contact the organiser. No Go Back button.
Page Not Found	The page ID does not exist or the API returns an error.	Heading Page Not Found, body Marketing page not found or The marketing page you are looking for does not exist.
Page Unavailable	The operator has hidden the page via Hide Page.	Lock icon 🔒, heading Page Unavailable, body This marketing page is currently not available.

Tip: Use the page states to diagnose link issues: No Marketing Page Configured = the link is malformed, Page Not Found = the page was deleted, Page Unavailable = the operator hid it temporarily.

2.2 Marketing page layout

When the page is configured, only sections enabled in the Ops Portal are shown:

• Logo header — the uploaded Company Logo, or a text fallback (the company name set in Step 2, defaults to Company).
• Banner carousel — auto-rotates between banners (~4 second interval). Banner tap behaviour depends on Banner Link:
  • Custom Link — opens an external HTTPS URL in a new tab.
  • Voucher Detail Page — opens the Member App voucher page in a new tab.
• Slogan — optional headline rendered below the banner (only when Slogan is filled in Step 2).
• Link Voucher section — section title is the Voucher section title entered in Step 3 (falls back to Vouchers if left blank). Each card shows the voucher image, name, token icon and symbol, and price (or Free when zero).
• Link Campaign section — section title is the Campaign section title entered in Step 3 (falls back to Campaign if left blank). Loading state Loading vouchers...; empty state No vouchers available for this campaign.
• Let's Discover More CTA — opens {base}/sso-login in a new tab when an SSO URL is available; otherwise rendered as a disabled button with the same label.

Tip: Banner taps and voucher cards always open in a new tab. Members can use the OS / browser back gesture to return to the marketing page.

What happens when a member taps a voucher card

The marketing page opens the Member App voucher page for that voucher in a new tab. On that page members see the voucher image, title, token price, validity, merchant, description and terms, and a fixed Redeem button at the bottom. The button label / behaviour depends on the member's login state and the voucher status:

Member state	Tap Redeem behaviour
Logged in to the Member App (session active in the same browser)	The button reads Redeem. Tapping it redeems the voucher immediately; on success the toast Voucher redeemed successfully! appears and the page navigates to the claimed voucher's detail screen.
Not logged in	The button still reads Redeem, but tapping it opens the Login Prompt modal with the message Please log in to claim vouchers. The member must log in (or sign up) before retrying.

---

3. Ops Portal - Marketing Page List

The Marketing Ops Portal opens by default on the Marketing Page list at /marketing.

3.1 Page layout

• Title — Marketing Page.
• + Create New Marketing Page (top right) — opens the 4-step wizard at /marketing/create.
• Search input (placeholder Search by name...) — filters the list by marketing page name.
• Hidden badge — appears next to the page name when Hide Page is on.
• Empty state — title No Marketing Page with the link Create new marketing page.

Pages table columns: Marketing Page ID (used in the public URL /marketing/{id}), Marketing Page Name, Created Date Time, No. of Banner (max 5), Link Voucher, Link Campaign, Actions.

Note: The Ops Portal does not currently expose Import / Export — pages are created one at a time using the wizard.

3.2 Row actions

• View Details — opens the read-only wizard.
• Edit — opens the 4-step wizard at /marketing/edit/{id} for in-place edits.
• Delete — opens Delete Marketing Page (Are you sure you want to delete this marketing page?, buttons Cancel / Delete). Success toast: Marketing page deleted successfully!.
• Download QR — opens the QR Code modal. The modal contains:
  • The QR code itself (Download QR Code button below it; saves as qr-code-{name}.png, success toast QR code downloaded successfully!).
  • Marketing Page Link label, the link text ({pwaBaseUrl}/marketing/{id}), and a Copy link icon button. Success toast: Link copied to clipboard!. If the browser blocks clipboard access, a fallback prompt asks the member to Copy this link (select the text, then Cmd/Ctrl+C):.
• Hide Page / Unhide Page — toggles the hidden flag. Hidden pages show Page Unavailable to members and the Hidden badge appears next to the row name.

3.3 How to use

How to use:

1. Open Marketing from the Admin Portal.
2. Use the Search input at the top of the list to find an existing page, or click + Create New Marketing Page to start a new one.
3. To share a page with members, click Download QR on the row — copy the Marketing Page Link or download the QR image and distribute it through your chosen channels (email, social, print, in-app push).
4. Use Hide Page to temporarily take a page offline; members opening the link see Page Unavailable. Use Unhide Page to restore visibility.
5. Use Delete only when the page will never be needed again — the action is permanent and the link starts returning Page Not Found.

---

4. Ops Portal - Create / Edit Marketing Page

Both Create and Edit share a 4-step wizard. The breadcrumb reads Marketing page > Create New Marketing Page (or Edit Marketing Page).

Stepper:

1. Basic Setting
2. Banner Details
3. Content Configuration
4. Confirmation of creation (renders as Confirmation of changes in edit mode)

The footer shows Cancel on Step 1, Back on Steps 2-4, Next between steps, and Create (or Save in edit mode) on the final step.

4.1 Step 1 — Basic Setting

• Marketing Page Name (required, max 30 chars, placeholder Enter marketing page name) — also appears in the list view and breadcrumb.
• Description (required, max 200 chars, placeholder Enter description, multi-line rows={6}).

4.2 Step 2 — Banner Details

• Click Add Banner to open the Add Banner modal:
  • Banner Title — placeholder Enter banner title, max 30 chars.
  • Banner Image — JPG, PNG, GIF or WEBP (Max 5MB, square ratio). Non-GIF images go through a 1:1 crop dialog (Crop Image, Zoom:, Confirm Crop). GIFs skip the crop step with a toast explaining the limitation.
  • Banner Link — choose Voucher Detail Page (click Select → Select Voucher modal with a Search input (placeholder Search by voucher name) plus filters Brand, Category, Voucher Type, Country) or Custom Link (placeholder https://example.com, validation Please enter a valid URL (e.g., https://example.com) — only http:// / https:// accepted).
  • Submit button: Add Banner (create) or Confirm (edit).
• Up to 5 banners. Adding a 6th triggers Maximum 5 banners allowed.
• Banner table columns: Banner Title, Banner Image, Banner Link, plus row Edit / Delete. Empty state: No banners added yet.
• Slogan — optional, max 30 chars, placeholder Enter slogan.
• Company Logo — upload via Click to upload image, JPG or PNG (Max 5MB). Cropping uses the Crop Company Logo dialog (Drag the corners or edges...).

Warning: UI limit is 5 MB per banner image, but the backend uploader allows up to 10 MB. Always respect the UI limit when uploading from the Ops Portal.

4.3 Step 3 — Content Configuration

Configure what sections appear on the marketing page itself. At least one of Link Voucher or Link Campaign must be enabled before Next becomes active.

• Link Voucher — toggle on, set Voucher section title (placeholder Enter title, max 30 chars, defaults to Vouchers on the member page). Add Voucher opens the Select Voucher modal (a Search input with placeholder Search by voucher name, same filters as the banner picker, paginated with Previous / Next, footer action Add Voucher (n)). Selected vouchers are listed with columns Voucher, Voucher Type, Price, Brand, Available Quantity, Validity Period, Category, Country (empty state No vouchers added yet). Expired vouchers are filtered out of the picker.
• Link Campaign — toggle on, set Campaign section title (defaults to Campaign), then choose a campaign in the Campaign dropdown (placeholders Loading campaigns... / Select Campaign).

4.4 Step 4 — Confirmation

Review every section (Basic Setting, Banner Details, Content Configuration) before saving, then click Create (create mode) or Save (edit mode). Success toasts: Marketing page created successfully! / Marketing page updated successfully!, after which the portal returns to the Marketing Page list.

---

5. Operational Workflows

5.1 Launch a new marketing page

1. Click + Create New Marketing Page in the Ops Portal.
2. Step 1 — set Marketing Page Name and Description.
3. Step 2 — add up to 5 banners (with Voucher Detail Page or Custom Link targets), plus optional Slogan and Company Logo.
4. Step 3 — enable Link Voucher and/or Link Campaign and configure their section titles, vouchers, and campaign selection.
5. Step 4 — review every section and click Create.
6. From the list view, click Download QR to obtain the Marketing Page Link and / or QR image, then distribute the link through your chosen channels.
7. Open the link on a test device to confirm banners, voucher cards, campaign vouchers, and Let's Discover More behave as expected.

5.2 Edit a live marketing page

Warning: Edits go live as soon as Save is clicked. Members refreshing the page will see the latest banners and vouchers immediately.

1. Click Edit on the row.
2. Adjust the relevant step (rename, replace a banner image, swap vouchers, change the campaign).
3. Step through to Step 4 and click Save.
4. Verify on a test device. If the change is disruptive, Hide Page first, save, verify, then Unhide Page.

5.3 Temporarily hide a page

1. Click Hide Page on the row.
2. Members opening the link see Page Unavailable (lock icon).
3. Click Unhide Page to bring the page back online.

5.4 Delete a marketing page

1. Click Delete on the row.
2. Confirm in the Delete Marketing Page modal.
3. The page is removed permanently and the marketing link starts returning Page Not Found.

---

6. Troubleshooting

For members

Symptom	What to check
Page blank / endless spinner	Reload the link in the browser. If opened from inside the Member App, tap the Refresh icon in the Member App shell.
No Marketing Page Configured	The link does not include a marketing page ID. Ask the marketing team for a valid link.
Page Not Found	The marketing page ID is invalid or was deleted in the Ops Portal.
Page Unavailable (lock icon)	The operator has hidden the page. Try again later.
Banner or voucher card does nothing on tap	Confirm pop-up / new-tab permission is granted in the browser.
Voucher cards open with an invalid URL	The marketing PWA could not resolve the Member App URL; ask the operator (or engineering) to confirm the configured Member App URL.

For operators

Symptom	What to check
Add Banner disabled or shows Maximum 5 banners allowed	The page already has 5 banners. Remove one before adding another.
Confirm Crop never enables	The image is a GIF — GIFs skip the crop step. Other validation (size, ratio) may still fail.
Select Voucher lists nothing	Confirm the VIO External API Key is configured (the gate must be cleared) and that the campaign has not expired.
Banner Custom Link validation keeps failing	The URL must start with http:// or https://.
Copy link toast says Link copied to clipboard! but paste is empty	Browser blocked clipboard access (Permissions-Policy or non-secure origin). Use the fallback prompt or copy manually from the visible link text.
Members still see the old content	Banner images are cached client-side; ask the member to reload the link (or tap Refresh if opened inside the Member App).
VIO External API Key modal keeps reappearing	The saved key is invalid or revoked. Paste a fresh vio_live_… key and click Confirm.

---

7. Business Rules & Notes

• Distribution — Marketing pages are shared by link or QR generated in the Ops Portal. The link is a standalone URL ({pwaBaseUrl}/marketing/{id}) and works in any modern browser; it also renders inside the Member App shell if opened from there.
• Banner cap — Maximum 5 banners per page (UI). UI image limit 5 MB, backend uploader allows up to 10 MB — always respect the UI limit.
• Image formats — Banner: JPG, PNG, GIF, WEBP (square ratio). Company Logo: JPG, PNG (max 5 MB).
• Custom Link — Only http:// and https:// URLs are accepted. Invalid input is rejected with Please enter a valid URL (e.g., https://example.com).
• Voucher / Campaign integration — Vouchers and campaigns are fetched from the VIO External API. Already-expired vouchers are filtered out of the picker.
• Visibility — Controlled by Hide Page / Unhide Page. There is no separate draft / published lifecycle — every saved page is live unless hidden.
• Editing live pages — Changes go live immediately after Save. Hide the page first if you need to stage a large edit.
• Tenant-specific content — Company logo, slogan, banners, voucher pool, and campaign linkage all vary by tenant. The defaults rendered to members (Vouchers, Campaign, Let's Discover More) are fixed strings.
• Compliance — Marketing copy should align with the linked vouchers and campaigns. Surface privacy / terms links via Custom Link banners where regional rules require them.

---

See also Mini Apps overview, Lucky Draw Mini App, Claim Mini App, Registration Reward Mini App, and Admin Portal - Branding.