PWA configuration.

Your loyalty software can work like a mobile app, with no app-store download. 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 software:

• Home screen icon: Launch with one tap, like a regular app
• Offline access: View cached loyalty cards and QR codes without internet
• Faster loading: Previously visited pages load without delay
• 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 (8th tab)

Configuration options

App name

The full name of your loyalty software. 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. It often 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 at once. The manifest.json file updates on save. Staff surfaces ship a separate manifest (staff-manifest.json), so the counter dashboard installs as its own app with a distinct identity.

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 as expected
4. Check that icons load without errors

On mobile

1. Visit your loyalty software 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

The fastest way to preview the offline screen is to open /<locale>/offline while online (for example /en-us/offline). It renders the same screen the service worker serves, populated with whatever cards you have cached.

To test the genuine offline behavior:

1. While online, open My Cards (and a card or two) so the service worker registers, caches the offline screen, and stores your cards' QR codes.
2. Open DevTools → Application → Service Workers and tick Offline, or enable airplane mode on a phone.
3. Navigate to a card page you haven't opened yet, or reload. The offline screen appears with your saved cards; tap one to show its QR full-screen.

Landing on an old version? That's the service worker serving its cached copy. See Seeing an Old Version After an Update for the reliable reset.

Member experience

What members see

When members visit your installation:

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: A banner appears at the bottom of the screen to let members know their saved cards are on display. It matches the rest of the app and appears in the member's language.

The banner disappears when the connection returns.

How offline caching works

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

1. Page caching (member-only): The service worker caches the member-facing pages you visit
2. Card pre-caching: The app caches every loyalty card, stamp card, voucher, and prepaid pass visible on a page
3. QR code generation: The app generates QR codes and stores them on the device for offline display
4. Smart updates: Cards refresh when you open them again after 1 hour

This means browsing the homepage or "My Cards" page caches all visible cards. No need to open each card one by one.

What works offline

• Viewing cached pages: Previously visited pages load from cache
• Browsing saved cards: All four card types (loyalty cards, stamp cards, vouchers, and prepaid passes) cached during online browsing, gathered into one searchable, filterable list
• Displaying QR codes: Members can still show their QR code offline so staff can scan it
• Viewing balances and progress: Points, stamps, voucher values, and remaining pass visits

The offline page

If a member opens the app (or navigates to a page) with no connection, the PWA shows a dedicated offline screen:

• A searchable list of every saved card (loyalty cards, stamp cards, vouchers, and prepaid passes), each with a type icon, name, and balance
• A search box and per-type filters, so a member who carries dozens of cards finds the right one fast
• Tapping a card opens its QR code full-screen, ready to scan at the counter
• The app formats point balances (e.g. 433,244), and the whole screen appears in the member's language

This ensures members can always show their loyalty cards to staff, even without internet access.

The staff offline screen

Staff who use the app at the counter see a different offline screen. Because every staff action (awarding points, adding stamps, selling passes, redeeming rewards) needs a live connection to record the transaction, there are no cards to cache, so staff get a simple reconnect prompt that matches the app's design and reconnects when the connection returns. Like the member offline screen, it appears in the staff member's language.

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

Seeing an old version after an update

Cause: A PWA installs a service worker that serves its own cached copy of the app until it detects and activates a newer version. Right after you deploy an update, a browser or installed app that still holds the previous service worker can keep showing the old screens or assets for a visit or two. This is normal PWA behavior, not a fault.

Solution (most reliable):

1. Open DevTools → Application → Storage → Clear site data. This removes the service worker, its caches, and stored cards in one click.
2. Reload the page while online. A fresh service worker registers and re-caches the current version.

While testing right after an update, keep DevTools → Application → Service Workers open and tick Update on reload, so every reload activates the newest service worker; Unregister there forces a clean slate. On a phone, fully close and reopen the installed app, or remove it from the home screen and re-add it, to achieve the same.

💡 Tip: To preview only the offline screen without any of this, open /<locale>/offline (for example /en-us/offline) while online. It renders the same screen the service worker serves.

Note: Members rarely need to do this; the service worker updates itself in the background within a visit or two. It matters most when you're testing right after deploying an update.

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. The app caches cards when they are 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 as a regular website.

Storage

• QR codes use approximately 5-10 KB each
• The app caches up to 50 cards (it removes the oldest when the limit is reached)
• Browser storage quota is usually 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 installation's visual identity
• Requirements: Server and HTTPS requirements
• Common Issues: General troubleshooting