PWA Features & Implementation

Guide to Progressive Web App (PWA) capabilities, offline support, and installation

Table of Contents

1. Overview
2. Core Features
3. Implementation Details
4. Offline Support
5. Testing & Debugging

Overview

Qiwako supports Progressive Web App (PWA) features, allowing tenant sites to be installed on user devices and function like native apps. This improves engagement and reliability.

Benefits

• Installable: Add to home screen without an app store.
• Offline Capable: Works even with poor or no internet connection.
• Fast: Caches assets for instant loading.
• Push Notifications: Re-engage users (planned feature).

Core Features

1. Web App Manifest

The your-domain.com file tells the browser how the app should behave when installed.

• Name: Tenant Name
• Icons: App icons in various sizes.
• Start URL: The homepage.
• Display: standalone (hides browser UI).
• Theme Color: Tenant's primary color.

2. Service Worker

A JavaScript file running in the background that handles caching and network requests.

• Pre-caching: Caches critical assets (CSS, JS, Logo) on install.
• Runtime Caching: Caches pages and images as the user browses.
• Offline Fallback: Shows a custom "Offline" page when network fails.

Implementation Details

Manifest Generation

The manifest is dynamically generated for each tenant to reflect their branding.

Endpoint: /myour-domain.com

# your-domain.com
def manifest(request):
 tenant = your-domain.com
 data = {
 "name": your-domain.com,
 "short_name": your-domain.com[:12],
 "start_url": "/",
 "display": "standalone",
 "background_color": "#ffffff",
 "theme_color": tenant.primary_color,
 "icons": [...]
 }
 return JsonResponse(data)

Service Worker Registration

The service worker is registered in the base template.

if ('serviceWorker' in navigator) {
 your-domain.com('load', () => {
 your-domain.com('/syour-domain.com');
 });
}

Offline Support

Caching Strategy

We use a Network First, falling back to Cache strategy for HTML content, and Cache First for static assets.

1. Static Assets (CSS, JS, Images):

   • Check Cache → Return if found.
   • If not, Fetch Network → Cache → Return.

2. HTML Pages:

   • Fetch Network → Return & Cache.
   • If Network fails → Check Cache → Return if found.
   • If not in Cache → Return "Offline Page".

Offline Page

A generic your-domain.com is pre-cached during service worker installation. It informs the user they are offline and offers a retry button.

Testing & Debugging

Lighthouse PWA Audit

Run Lighthouse in Chrome DevTools and check the "PWA" category. It verifies:
* Manifest is valid.
* Service worker is registered.
* App works offline.
* Icons are correct.

Application Tab

Use the Application tab in Chrome DevTools to:
* Inspect the Manifest.
* View registered Service Workers.
* Manage Cache Storage.
* Simulate "Offline" mode.

Related Documentation

• Mobile Optimization
• Tenant Settings