PWA Configuration.

Your loyalty platform can work like a mobile app—without requiring users to download anything from an app store. Members can install it to their home screen and access their loyalty cards even without an internet connection.

What Is a PWA?

A Progressive Web App (PWA) is a website that behaves like a native mobile app. When members install your loyalty platform:

• Home screen icon — Launch with one tap, just like a regular app
• Offline access — View cached loyalty cards and QR codes without internet
• Faster loading — Previously visited pages load instantly
• App-like experience — Full-screen mode without browser chrome

Requirements

For production:

• HTTPS certificate (required by all browsers)
• Modern browser (Chrome, Safari, Firefox, or Edge)

For local development:

• http://localhost works without HTTPS
• No certificate needed for testing

💡 Tip: Most hosting providers include free SSL certificates. Contact your host if you need help enabling HTTPS.

Accessing PWA Settings

1. Navigate to Settings in the admin sidebar
2. Select the PWA tab (5th tab)

Configuration Options

App Name

The full name of your loyalty platform. This appears:

• When using the browser's "Add to Home Screen" feature
• In browser app management
• On splash screens

Leave blank to use your system's default app name.

Short Name

A condensed version (maximum 12 characters) displayed under the home screen icon.

Example: "Reward Loyalty" becomes "Rewards"

⚠️ Important: This field is required. Keep it short and memorable.

Description

A brief explanation (maximum 132 characters) shown during installation. Think of it as an elevator pitch.

Good: "Earn rewards at local businesses"
Bad: "Loyalty card platform system for customer management"

Theme Color

The color of the browser's address bar when the app is running. Typically matches your primary brand color.

Format: Hex color code (e.g., #4F46E5)

Background Color

The splash screen background color shown while the app loads on Android devices. Usually white or a light brand color.

Format: Hex color code (e.g., #ffffff)

💡 Note: Splash screens with a centered icon work on Android, but not on iOS. iOS requires device-specific full-screen images for each screen resolution, which isn't currently supported. iOS users will see a brief white screen while the app loads.

App Icons

Upload square icons in two sizes:

Supported formats: PNG, JPEG, WebP

Design tips:

• Use PNG for transparency support
• Include 10% padding for safe cropping (iOS crops icons into circles)
• Ensure the icon is recognizable at small sizes
• Use solid, contrasting colors

Saving Changes

1. Fill in required fields (Short Name, Description, Theme Color, Background Color)
2. Upload icons (optional—defaults will be used if skipped)
3. Click Save Changes
4. Success message confirms your settings are saved

Changes take effect immediately. The manifest.json file updates automatically.

Testing Your PWA

On Desktop

1. Open browser DevTools (F12 or right-click → Inspect)
2. Go to Application tab → Manifest
3. Verify all fields display correctly
4. Check that icons load without errors

On Mobile

1. Visit your loyalty platform on your phone
2. Use your browser's built-in installation option:
   • iOS Safari: Tap Share → "Add to Home Screen"
   • Android Chrome: Tap menu → "Install app"
3. Complete installation
4. Launch from home screen

Testing Offline Access

1. Install the PWA
2. Visit a loyalty card page
3. Enable airplane mode on your device
4. Open the installed app
5. Verify your QR code still displays

Member Experience

What Members See

When members visit your platform:

1. Automatic caching — Cards visible in the member experience (homepage, My Cards, card pages) are cached in the background
2. Install option — Members can use the browser's "Add to Home Screen" feature to install the app
3. Offline access — If connection is lost, cached pages and cards remain available
4. Offline indicator — An amber banner appears: "You're offline. Showing cached cards."

The banner automatically disappears when the connection returns.

How Offline Caching Works

The PWA uses aggressive pre-caching to ensure cards are available offline:

1. Page caching (member-only) — Member-facing pages you visit are cached by the service worker
2. Card pre-caching — All loyalty cards, stamp cards, and vouchers visible on a page are cached automatically
3. QR code generation — QR codes are generated and stored locally for offline display
4. Smart updates — Cards are refreshed if visited again after 1 hour

This means browsing the homepage or "My Cards" page caches all visible cards—no need to open each card individually.

What Works Offline

• Viewing cached pages — Previously visited pages load from cache
• Viewing loyalty cards — All cards visible during online browsing
• Displaying QR codes — Members can still show their QR code offline so staff can scan it
• Viewing stamp cards and progress — See your stamps and rewards
• Viewing saved vouchers — Access your discount codes

The Offline Page

If you navigate to a page that wasn't cached, the PWA shows a dedicated offline page featuring:

• A grid of all your cached loyalty cards
• Each card displays its name, balance/stamps, and scannable QR code
• Cards sorted by most recently viewed
• Relative timestamps ("2 hours ago", "Yesterday")

This ensures you can always show your loyalty cards to staff, even without internet access.

What Requires Internet

• Earning new points or stamps
• Redeeming rewards
• Browsing new programs
• Account changes

Important: Offline mode is designed so members can always present their QR code. Staff actions (awarding points, adding stamps, redeeming rewards) still require an internet connection to record the transaction.

Troubleshooting

PWA Not Installing

Most common cause: Your site isn't using HTTPS.

Solution:

1. Check that your URL starts with https://
2. Verify no mixed content warnings (some resources loading over HTTP)
3. Contact your hosting provider to enable SSL

"Add to Home Screen" Not Appearing

Causes:

• Site not using HTTPS (required for PWA features)
• Mixed content warnings (some resources loading over HTTP)
• Browser doesn't support PWA features

Solution: Use the browser menu to install:

• Chrome: Menu → "Install app" or "Add to Home Screen"
• Safari: Share button → "Add to Home Screen"
• Firefox: Menu → "Install"

Icons Not Updating

Cause: Browser cached old manifest.

Solution:

1. Clear browser cache
2. Uninstall and reinstall the PWA
3. Wait up to 24 hours for cache expiration

QR Code Not Showing Offline

Cause: The card page wasn't visited while online.

Solution:

1. Visit any page showing the card while connected to the internet (homepage, My Cards, or the card detail page)
2. Cards are cached automatically when visible on screen
3. Test offline access afterward

💡 Tip: Visiting the "My Cards" page once while online caches all your saved cards for offline use.

Pages Not Loading Offline

Cause: The specific page wasn't visited while online.

Solution:

1. The PWA caches pages as you visit them
2. Browse the pages you need while connected
3. The service worker will serve cached versions when offline

Note: The PWA prioritizes serving cached pages. Only if a page wasn't cached will it show the offline page with your QR codes.

Best Practices

Icon Design

• Don't use transparent backgrounds for the 192×192 icon
• Do test how the icon looks cropped in different shapes
• Do use your brand's primary logo or recognizable symbol
• Don't include text that becomes unreadable at small sizes

Color Selection

• Do match theme color to your brand's primary color
• Do use a light background color for readability
• Don't use extremely bright or neon colors
• Do test colors on both light and dark device themes

Naming

• Do make the short name memorable and brandable
• Don't use generic names like "App" or "Loyalty"
• Do test how the name displays under a home screen icon

Technical Details

Browser Support

Unsupported browsers won't have the "Add to Home Screen" or "Install app" option available. Your site still works normally as a regular website.

Storage

• QR codes use approximately 5-10 KB each
• Up to 50 cards can be cached (oldest cards are automatically removed when the limit is reached)
• Browser storage quota is typically 50-100 MB
• Page cache is managed separately and can store many visited pages

Updates

• Service worker updates when you deploy changes
• Updates happen on page refresh
• May take up to 24 hours for complete propagation

Related Topics

• Branding — Customize your platform's visual identity
• Requirements — Server and HTTPS requirements
• Common Issues — General troubleshooting