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

This module is optional

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:

Name	Default value	Note
Enabled	No
Name		required Application name displayed on the splash screen below the icon.
Short name		required Application name displayed in the application drawer or on the home screen.
Description		required Application description, not displayed anywhere but can be used by app stores in the future.
Start URL when not logged in	Home Page	Page which should be loaded when users open the application and is not logged in.
Start URL when logged in	Home Page	Page which should be loaded when users open the application and is logged in. It can also Custom Url
Custom Start URL when logged in		f.e. sales/order/history
Offline page URL	About us	Page which should be shown when user device is offline.
Display mode	Minimal UI	required The way the installed application will be displayed. Please refer to https://web.dev/add-manifest/#display for a detailed description of each mode.
Background color	#FFFFFF	required Background of the splash screen, the one displayed when the application is loading for the first time.
Theme color	#FFFFFF	required General theme color of the application, used as the status bar background.
Categories	shopping,fitness,sports	required List of categorizations you want to apply to your site. Categories should be lower cased and comma separated. There are no pre-defined categories, but the W3C maintains a list of known categories.
Debug mode enabled	No	Enables service worker debug mode.

Display modes

By default, minimal-ui mode is selected.

There are 4 display modes:

fullscreen
Opens the web application with browser UI elements hidden and takes up the entirety of the available display area.
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.
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.
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 worker is the technology that enables your app to use many Progressive Web App features, such as offline, add to homescreen, and push notifications. With proper service worker and manifest implementations, browsers can proactively prompt users to add your app to their homescreen, which can lead to higher engagement

Service worker

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"/>

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

service-worker.phtml

service-worker/workbox.phtml
service-worker/static.phtml
service-worker/media.phtml
service-worker/mobile-navigation.phtml
service-worker/product-reviews.phtml
service-worker/google-fonts.phtml
service-worker/offline-pages.phtml
service-worker/offline-fallback.phtml

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

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();

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 possibility to adjust basic styling by adjusting scss variables.

Backend

TODO - BE documentation and review of documentation is needed

Pwa (optional)