SiteEase Progressive Web App Plugin details and feature guide Plugin name: SiteEase Progressive Web App Plugin slug: iflair-pwa-app Version: 1.1.6 Author: iFlair Web Technologies Pvt. Ltd. Text domain: iflair-pwa-app 1. PURPOSE SiteEase Progressive Web App adds Progressive Web App capabilities to a WordPress website. It generates a web app manifest, registers a service worker, provides configurable cache behavior, supports offline pages, and can show an install prompt in supported browsers. A PWA still depends on browser support and site configuration. Service workers require HTTPS on production websites. The localhost exception is supported by browsers for local development. 2. ADMIN SETTINGS The plugin adds a SiteEase Progressive Web App menu for administrators. The settings page contains Basic Settings, Caching Strategies, and Advanced tabs. 2.1 Basic Settings Display custom button in footer? Enables the browser install prompt UI supplied by the plugin. When the browser fires beforeinstallprompt, the plugin displays a small floating button. Clicking it opens an install confirmation dialog. This feature is mainly supported by Chromium-based browsers. iOS Safari does not provide the same event and requires its own manual Add to Home Screen flow. App Name Sets the manifest name. This is the name shown in an installed app launcher, home screen, or task switcher. If no value is stored, the WordPress site name is used. App Short Name Sets the shorter manifest name used where space is limited. If it is empty, the App Name is used. App Icon Selects the 192x192 PNG icon used for installation and the app shortcut. Select an image in the WordPress media library. If no icon is selected, the manifest omits empty icon entries. Space Screen Icon Selects the 512x512 PNG icon used for larger installation or splash-screen contexts. Background Color Sets the manifest background_color used while the installed app is loading. Theme Color Sets the browser and operating-system theme color. The same value is also written to the frontend theme-color meta tag. Start Page Selects the page opened when the installed PWA starts. UTM parameters are added using the configured campaign values. Offline Page Selects the page returned when the requested resource cannot be fetched and is not already cached. The selected page should be publicly accessible and should be included successfully during service-worker installation. Orientation Controls the installed app orientation. Available values are Any, Portrait, and Landscape. Display Controls the installed app presentation. Available values are Full Screen, Standalone, and Minimal UI. Browser support can affect the final presentation. Text Direction Controls the manifest direction for the app UI. Available values are LTR and RTL. 2.2 Caching Strategies Caching Strategy Type The service worker supports these strategies: - Network first, then Cache: fetches from the network first and falls back to cached content or the offline page when the request fails. - Cache first, then Network: serves cached content first and fetches from the network only when no cached response exists. - Stale While Revalidate: returns cached content immediately when available and updates the cache from the network. Existing installations using the legacy value steal_while_revalidate continue to work. - Cache only: serves only resources already in the cache. - Network only: always uses the network and does not read from the cache. The plugin excludes WordPress administration, login, preview, cart, AJAX, and login URLs by default. Requests carrying WordPress login or WooCommerce session/cart cookies also bypass caching. Additional exclusions can be configured in Advanced settings. Manual Pre-Caching Accepts a comma-separated list of URLs. These URLs are added to the service worker installation cache. URLs should be publicly reachable, use the correct site protocol, and return successful responses. Invalid or unavailable entries are skipped so one failed URL does not abort installation. 2.3 Advanced Settings Offline Analytics When enabled, the generated service worker loads Google Workbox from the Google CDN and initializes Workbox Google Analytics support. This is intended to help handle analytics events while the user is offline and synchronize them when connectivity returns. This feature requires a configured Google Analytics integration and access to the Workbox CDN. Enabling it introduces an external CDN dependency. Disable it when Google Analytics is not used or when external analytics dependencies are not desired. Cache External Origin URLs Controls whether requests to external origins may be handled by the service worker cache. Enable this only when external resources are trusted, cacheable, and permitted by their server headers. Cross-origin restrictions and opaque responses can limit what the browser can cache. Exclude URLs from Cache list Accepts a comma-separated list of URL patterns or URLs that should not be cached. These values are added to the service worker exclusion list. Use this for dynamic, private, checkout, account, or otherwise sensitive resources. 3. GENERATED FILES The plugin generates these files in wp-content/uploads/iflair-pwa-app/ and also mirrors them at the WordPress installation root so the service worker can control the site scope: - ifpwap-manifest.json: the web app manifest. - ifpwap-register-sw.js: frontend registration code for the service worker. - ifpwap-sw.js: the generated service worker containing cache and offline behavior. The files are generated after WordPress reaches the wp_loaded hook, only when files are missing, settings have changed, root availability changes, or generation is pending after activation. Settings changes become effective after the generated files are refreshed and the browser updates its service-worker registration. Browsers may retain an older worker briefly; use the browser application tools to inspect or unregister it during testing. 4. SERVICE-WORKER BEHAVIOR During installation, the worker creates a versioned cache and pre-caches the selected start page, offline page, and manual URLs. Individual pre-cache failures are logged and do not prevent the worker from installing. During activation, old plugin caches are deleted and the worker claims eligible clients. During fetch handling, excluded URLs bypass the worker. Non-GET requests use the network and do not use the offline HTML fallback. GET requests use the selected caching strategy. Range requests bypass service-worker caching and are sent directly to the network to avoid breaking audio, video, PDF, and other partial-content responses. The root service-worker file is required for a service worker to control the full WordPress installation scope. If the hosting environment does not allow the root file to be written or read, the plugin reports this in the admin status panel and registers the uploads-directory worker only for its narrower uploads scope. An uploads-directory worker cannot automatically control the WordPress root. Manifest icons use the selected WordPress attachment URL, MIME type, and actual dimensions when available. The configured Monochrome Icon is emitted with purpose monochrome. Existing App Icon and Space Screen Icon settings remain unchanged; the Space Screen Icon continues to provide any and maskable entries. 5. INSTALLATION AND OPERATION REQUIREMENTS - Use HTTPS on production websites. - Make sure the WordPress Home URL and Site URL use the same public origin. - Select valid PNG icons in the media library. - Select a public start page and offline page. - Do not pre-cache private, authenticated, or non-cacheable URLs. - Test installation and offline behavior in a supported browser. - Clear or update an existing service-worker registration after major settings changes. 6. PRIVACY AND EXTERNAL SERVICES The plugin does not itself create user accounts or store personal profile data. When Offline Analytics is enabled, the generated worker loads Google Workbox from: https://storage.googleapis.com/workbox-cdn/releases/6.0.2/workbox-sw.js Google Analytics behavior depends on the website's own analytics configuration. Website owners should review their analytics, consent, and privacy requirements before enabling Offline Analytics. 7. TESTING CHECKLIST 1. Open the frontend and inspect the manifest link. 2. Open the manifest URL and confirm valid JSON, name, start_url, scope, colors, direction, and icons. 3. Confirm the service-worker registration succeeds in browser developer tools. 4. Confirm the worker scope covers the intended WordPress site path. 5. Reload once online so the start and offline pages are cached. 6. Use browser offline mode and open a cached page. 7. Open an uncached URL offline and confirm the configured offline page is returned. 8. Verify excluded URLs are not intercepted or cached. 9. Change a caching strategy, save settings, and confirm the generated worker contains the new strategy. 10. Test the install prompt only in a browser that supports beforeinstallprompt.