https://github.com/magesuite/pwa

The module adds PWA service workers. By using this PWA feature a shop offers its customers the option to add your app to the home screen of their device. On the success page, PWA guide is displayed either as a short note or as a modal. The content of the guide is different for Android, IOS, and desktop devices.

Installation

composer require "creativestyle/pwa" ^1.0.0

User guide

4.10.Progressive Web App Features

4.10.1. Add to homescreen

4.10.2. Offline CMS page

Admin settings

Configuration can be found in the admin panel:
Stores > Configuration > Magesuite > PWA

Configure the Enabled option as Yes

Settings:

Display modes

By default, minimal-ui mode is selected.

There are 4 display modes:

1. fullscreen
   Opens the web application with browser UI elements hidden and takes up the entirety of the available display area.

2. standalone
   Opens the web application to look and feel like a standalone native application. This can include the application having a different window, its own icon in the application launcher, etc. In this mode, the user agent will exclude standard browser UI elements such as an URL bar, but can include other system UI elements such as a status bar and/or system back button.

3. minimal-ui
   This mode is similar to standalone, but provides the end-user with some means to access a minimal set of UI elements for controlling navigation (i.e., back, forward, reload, and perhaps some way of viewing the document's address). A user agent can include other platform specific UI elements, such as "share" and "print" buttons or whatever is customary on the platform and user agent.

4. browser
   Opens the web application using the platform-specific convention for opening hyperlinks in the user agent (e.g., in a browser tab or a new window).

Frontend

Service workers

Basics

Service workers are specialized JavaScript assets that act as proxies between web browsers and web servers. They aim to improve reliability by providing offline access, as well as boost page performance. https://developer.chrome.com/docs/workbox/service-worker-overview/

. With proper service worker and manifest implementations, browsers can proactively prompt users to add your app to their homescreen, which can lead to higher users engagement.

Service worker lifecycle

On the very first visit to a web page that installs a new service worker, the initial visit to a page provides its baseline functionality while the service worker downloads. After a service worker is installed and activated, it controls the page to offer improved reliability and speed. https://developer.chrome.com/docs/workbox/service-worker-overview/

Caching strategies

An indispensable aspect of service worker technology is the Cache interface, which is a caching mechanism wholly separate from the HTTP cache. The Cache interface is programmable through Javascript. Caching responses for network requests can be based on whatever logic is best for a given website. These scenarios are called caching strategies https://developer.chrome.com/docs/workbox/service-worker-overview/

An asynchronous and event-driven API

Service workers accommodate this asynchronicity through an event-driven API. Events can be registered using a familiar addEventListener API. All of these events can potentially interact with the Cache interface. async and await, those JavaScript features can also be used to simplify service worker.

Precaching and runtime caching

Isolation form main thread

Service workers occur on their own threads. This means service workers' tasks won't compete for attention with other tasks on the main thread.

Debugging service worker

Workbox

Why do we use workbox?

There's lots of complex interactions that are hard to get right [in service workers APi and logic]. Workbox is a set of modules that simplify common service worker routing and caching. Each module available addresses a specific aspect of service worker development. Workbox aims to make using service workers as easy as possible, while allowing the flexibility to accommodate complex application requirements where needed. https://developer.chrome.com/docs/workbox/what-is-workbox/

How service worker is composed in MageSuite

Registration

Before the body end register service worker template is added:

<block name="pwa.service-worker.register" template="MageSuite_Pwa::service-worker/register.phtml" after="-" ifconfig="pwa/general/is_enabled"/>

<?php
/** @var $block \MageSuite\Pwa\Block\Data */
$url = $block->getBaseUrl() . 'service-worker.js';
?>
<script>
if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('<?= /* @noEscape */ $url ?>');
}
</script>

service-worker.js file

pwa_serviceworker_index.xml layout composes service worker script ( service-worker.js ) with smaller templates.

templates/service-worker.phtml - parent template

Service worker file chunks

Import workbox script

service-worker/workbox.phtml - import workbox script and set optional debug mode (can be configured in the admin panel)

Detect requests for static files:

service-worker/static.phtml

Cache name: static

Route:

new RegExp('<?= /* @noEscape */ $staticBaseUrl ?>.+\.(?:png|gif|jpg|jpeg|webp|svg|js|css|html|json|woff|woff2)$'),

new workbox.strategies.CacheFirst({
  cacheName: 'static',
  plugins: [
    new workbox.expiration.ExpirationPlugin({
      maxEntries: 300,
      maxAgeSeconds: 30 * 24 * 60 * 60, // 30 Days
    }),
  ],
})

Use CacheFirst strategy: https://developer.chrome.com/docs/workbox/modules/workbox-strategies/#cache-first-cache-falling-back-to-network combined with workbox expiration plugin: https://developer.chrome.com/docs/workbox/modules/workbox-expiration/ with expiration time set to 30 days

Result: If there is an in the cache, it will served from the cache, otherwise there will be a network request and the response will be cached. An asset cache expires after 30 days. limit the number of entries in a cache to 300;

Detect requests for media files:

service-worker/media.phtml

Cache name: media

Use CacheFirst strategy: combined with workbox expiration plugin: with expiration time set to 30 days and number of entries: 300

Mobile navigation

service-worker/mobile-navigation.phtml

Cache name: mobile-navigation

Use CacheFirst strategy and limit the number of entries in a cache to 1.

Product reviews

service-worker/product-reviews.phtml

Cache name: product-reviews

Use StaleWhileRevalidate strategy.

Result: Respond to the request with a cached response if available, falling back to the network request if it's not cached. The network request is then used to update the cache. https://developer.chrome.com/docs/workbox/modules/workbox-strategies/#stale-while-revalidate

Offline pages

service-worker/offline-pages.phtml

when a page is reloaded navigation request is added to offline-pages cache for 1 hour.

Cache name: offline-pages

Offline fallback

service-worker/offline-fallback.phtml

Result: Display offline page when a user if offline;

Example of composer service-worker script: https://demo.magesuite.io/service-worker.js

Debugging workbox

Manifest

pwa_manifest_index.xml layout adds a link to manifest.json, which is generated based on admin configuration

Example of manifest.json: https://demo.magesuite.io/manifest.json

Meta tags

The module adds blocks into HTML head, which display meta tags with values configured in the admin panel

• theme-color.phtml

• manifest-meta.phtml

• apple-mobile-web-app-title.phtml

<block name="pwa.theme-color" template="MageSuite_Pwa::theme-color.phtml" ifconfig="pwa/general/is_enabled">
<block name="pwa.manifest.meta" template="MageSuite_Pwa::manifest-meta.phtml" ifconfig="pwa/general/is_enabled">
<block name="pwa.manifest.title" template="MageSuite_Pwa::apple-mobile-web-app-title.phtml">

PWA guide

The separate functionality is a PWA guide that helps users to understand the benefits connected with adding a shop app to Homescreen. The guide is displayed on checkout success page, after placing and order.

PWA guide script file can be found here: magesuite-pwa/view/frontend/web/js/pwa-a2hs-guide.js

Separate wordings are used for desktop, Android mobile devices and iOS mobile devices

  showAgainTime: 0, // Always show guide, even after user clicked close before. Set 2592000000 for 30 days
  headerIOS: $.mage.__('Install this webapp on your %device%'),
  descriptionIOS: $.mage.__('Tap at the bottom of the banner on the Thank You page on <span class="cs-pwa-a2hs-guide__install-icon"></span> and then tap "Go to Home Screen".'),
  headerAndroid: $.mage.__('Install this webapp on your phone'),
  descriptionAndroid: $.mage.__('Tap <b>Install</b>. <br>Follow the instructions on the screen.'),
  headerDesktop: $.mage.__('Install this webapp on your desktop'),
  descriptionDesktop: $.mage.__('Click "Install" <span class="cs-pwa-a2hs-guide__install-icon"></span> in the upper-right corner of the address bar. Follow the on-screen instructions to install the PWA.'),
  declineText: $.mage.__('No, thank you'),
  showmoreText: $.mage.__('Show PWA guide'),

If there is a need now to change wordings 2 approaches can be used.

The first way is to overwrite vendor/creativestyle/magesuite-pwa/view/frontend/templates/add-to-homescreen-guide-js-init.phtml and pass proper config there

<script type="text/x-magento-init">
{
    "*": {
        "Magento_Ui/js/core/app": {
            "components": {
                "pwa-guide": {
                    "component": "MageSuite_Pwa/js/pwa-guide",
                    "config": {
                        "headerDesktop": "New header title" 
                    }
                }
            }
        }
    }
}
</script>

Another way is to write a mixin and pass new options.

If there is a need to add longer texts static blocks with defined can be used. The content for guides will be displayed in a modal.

The following ids are used to create modal content for PWA Guide: pwa_guide_ios, pwa_guide_android, pwa_guide_desktop

$iOSBlockHtml = $cmsBlock->setBlockId('pwa_guide_ios')->toHtml();
$androidBlockHtml = $cmsBlock->setBlockId('pwa_guide_android')->toHtml();
$desktopBlockHtml = $cmsBlock->setBlockId('pwa_guide_desktop')->toHtml();

Custom IOS installation prompt

In order to inform users that s shop is also available as a PWA installation optional custom IOS prompt functionality is available in the module. On Android smartphones, this already works natively, after a short time of a user’s visit, a PWA installation prompt appears, and the app can be installed. Unfortunately, iOS currently does not support native installation prompts for PWAs like on Android devices. However, you can create a custom installation prompt to explain to users on iOS devices how to add the PWA to the home screen. Please note that this custom installation prompt for iOS devices is less seamless than the native installation prompt for Android devices. The user must manually follow the instructions to add the PWA to the home screen. Nevertheless, it is a viable method to help users on iOS devices install your PWA.

In Stores -> Configuration -> Magesuite -> PWA if the PWA is enabled set the `Enable custom IOS installation prompt to Yes:

There are some settings that can be configured per project:

allowedDisplaysBeforeHiding: 3,
hidingTime: 10 * 24 * 60 * 60 * 1000, // 10 days
showTimeout: 10 * 1000, // 10 seconds after page is loaded
text: $.mage.__('Tap the "Share" icon <span class="cs-pwa-a2hs-guide__install-icon"></span> at the bottom of the screen and select "Go to Home Screen".'),

The default settings will result in the following behavior:

• the prompt is shown after 10 seconds from the page load (on every page)

• the prompt is shown 3 times to a user

• after the prompt is shown for the 3rd time, it is hidden for the next 10 days

If there is a need now to change settings 2 approaches can be used.

The first way is to overwrite vendor/creativestyle/magesuite-pwa/view/frontend/templates/pwa-installation-prompt-ios-js-init.phtml and pass proper config there

<script type="text/x-magento-init">
{
    "*": {
        "Magento_Ui/js/core/app": {
            "components": {
                "pwa-installation-prompt-ios": {
                    "component": "MageSuite_Pwa/js/pwa-installation-prompt-ios",
                    "config": {
                        "showTimeout": "2",
                        ....
                        ....
                    }
                }
            }
        }
    }
}
</script>

Another approach is to write a mixin and pass new options.

In order to display the prompt only for some pages remove/add <block name="pwa.installation.prompt.ios"/> in corresponding xml-s.

Styling

As the module is optional styling for PWA guide must be enabled in entries/checkout.ts

import 'MageSuite_Pwa';

Scss file can be found in theme-creativeshop/src/MageSuite_Pwa/web/css/pwa-a2hs-guide.scss There is the possibility to adjust basic styling by adjusting scss variables.

Backend