When we were given the task of building a PWA (Progressive Web Application) for iSocket I found that in 2022 many developers who are not traditional app developers but web developers still don't know much about PWA, but in fact now it is their job to create a decent user experience on the web, and PWA is an integral part of it. I decided to write simple explanations for my developers and share this with you.
These developers are definitely not designers, so they understand app icons even less, that is why I published another article about app icons. I also wrote a piece for advanced users about PWA and service worker secrets and debugging that you probably won't find anywhere else.
CONVERTING A WEB PAGE INTO A PWA
“My main goal here is to explain the concept as a whole in a simple way for beginners”
I won't explain all the details, I will provide a lot of links to mostly official documentation or very good posts from other people. My main goal here is to explain the concept as a whole in a simple way for beginners using an example of converting a client web portal (or catalog page) into a Progressive Web App (PWA).
If you want to learn more about PWA, you should read Learn PWA from Google and probably take their New Progressive Web App training, and read MDN Web Docs here.
Concept
If the service you provide assumes that your customers have a web account (dashboard) that they log in with their password or other credentials, then you basically have a web application (web page). Your users may be accessing your portal through a browser, and your portal may already be optimized for mobile viewing. If not, then this is the first thing you need to do and I won't write about it here. And now you want to have an app. The easiest way is to make your web page act like an app, i.e. create a progressive web app, unless you need very unique features that PWA doesn't support. So, let's put it this way (I don't want to promote the wrong terminology, but it's just for simplicity): a PWA is just a web page that you can install on your phone (at least for our use case).
Use case: iSocket
Let's take a look at the above with an example we did for iSocket Systems. They have a web catalog of their products at www.isocketworld.com - as you can see, it's just a website. They also have an iSocket IoT Portal for their customers to manage iSocket devices on iot.isocketworld.com - which is what we called a web app above. And our task was to convert both of them into PWAs so that customers can install them on their phones and use them as an app, not just like a web page in a browser.
Here is the result on iPhone X:
On the first screenshot, you can see the catalog both in Safari and as a standalone application. The interesting part here is that the app has a dedicated storage for assets. If you go to the catalog, you will see that you can select your country and the device models will be displayed according to the country. You can see that the Safari session and the app show different countries because the Safari session and the app are independent. On the second screenshot, you can see the iSocket IoT Portal as a standalone app and the catalog behind it.
How to?
- Make your web page secure (https) and really look like an app - SPA is the best option.
- Create decent icons for all needs.
- Create a service worker file.
- Create a manifest file.
For the first point, I mentioned that your page really needs to look like an app and be secure - I won't go into details. For icons, read my ultimate guide here. Now let's try to explain the other two things simply.
Service Worker
"The current joke among web developers is Safari is the new Internet Explorer"
I noticed that this topic is the most unclear for beginners, so I explain simply and with a specific terminology that is not exactly correct but understandable by newcomers, as I noticed. Some time ago browser developers decided that they should allow web developers to use the browser in a way that the developers thought would be good for their users (let's leave out Apple here...), they created an API. Every browser has an API that your web page can use to communicate with the browser. You give instructions to this API through a so-called service worker file, let's say this way. This is the file you create on your server. This file is registered by the browser and the browser follows instructions given in that file. Here's what Google explains about service workers and here's from MDN and Microsoft - they use correct terminology if you want to know.
Above links are good, but I believe one of the best explanations of service workers for beginners, along with examples of its contents, comes from MDN here.
What is the content of the service worker file?
“I met a common misconception that this is a standard file that you only need to download from somewhere and place it in the root.”
I'm not going to cover this topic about the content of the file - see links above and see my piece for advanced users, I'm just explaining to you that this is a file that you create and you code the content of it. I met a common misconception that this is a standard file that you only need to download from somewhere and place it in the root. Well, when you read the above guides on service workers, it's true that you may not immediately understand that you need some kind of file and what its content is. No, this is not a standard file that you download somewhere, you code what you want, within the framework of the API standard for browsers, let's say so. And you can name this file as you wish and place it anywhere - you tell the location of your service worker file to the browser, as described below. If you are not a fan of reading specifications like that one, you can use some sources to help you create this file. Founded by Microsoft, PWABuilder is probably one of the best known resources for building a simple service worker file based on Workbox or testing your PWA, but I would argue that it is not the best solution for this task in 2022.
How does the browser knows that it should register your service worker [file]?
You tell the browser this by adding this little script to every page that is considered part of your app. For example, you include this script in your site's header or footer template. So you tell the browser, hey my service worker file is there, please register this for me (I keep trying to use simple terminology, which is not always exactly correct but should be understandable, I hope):
<script>
// Service Worker Registration
if ('serviceWorker' in navigator) {
if (navigator.serviceWorker.controller) {
//console.log('Active service worker found, no need to register')
} else {
// Register the service worker
navigator.serviceWorker.register('/assets/backend/pwa/service-worker-iot.js', {
scope: '/'
}).then(function(reg) {
console.log('Service worker has been registered for scope:'+ reg.scope);
}).catch(function(err) {
console.error('Service worker registration failed', err);
});
}
}
</script>This will cause the browser to register the service-worker-iot.js file located at /assets/backend/pwa/service-worker-iot.js for scope /. Again, this script is not something standard. You can handle registration a little or totally differently, depending on your needs.
Put the file anywhere I like? Name it as I like? Yes! How about Lighthouse reporting "Does not register a service worker that controls page and start_url"? Read more in my article for advanced user after you've become familiar with the manifest files (see below). There you will also find another way to register a service worker to overcome the problem of a renamed or incorrectly registered service worker.
What is the most important content of the service worker file?
I mentioned that I won't talk about the contents of the file, but let's have a little (read more in my article for advanced user). Well, the browser noticed our service worker file (we helped the browser to do this by specifying the path to the file in the service worker registration script) and what's next?
The correct terminology would be "service worker registration" or "our service worker registered", but since we coding instructions for the browser in the file and tell the browser where that file is, I've noticed that it's easy for beginners to understand it as "service worker file registration ". Please forget the wrong terminology from now on, I won't promote it.
Well, registered. The service worker is registered. What's next? The rest is described in the file itself. Read the links I provided about all the possible things you can put to that file. We need at least to install the service worker and activate it - this are the instructions that we give in the file. But what else? What do we really want the browser to do in the first place for our use case? Remember, we are converting our web page into an app.
Note that an install event of the service worker is not the same as installing your app!
For example, we want that when there is no Internet on the phone, and a person opens our application, he or she will see a message that there is no Internet and the application cannot be used - this was the case with the iSocket IoT Portal, because customers use this portal to manage their devices and this happens through a backend server that communicates with their devices, and the devices that control power, temperature and other things in their homes are cellular - nothing can work without the Internet on the phone and we must inform users about this if they open the app. That's when you need to create an offline page in the first place and tell the browser to cache that page for offline use - that's what you do exactly in the service worker file, you tell the browser to cache that offline page with all assets and open it when no internet is detected. The user will see this (first is for the portal, second is for the catalog):
“In fact, offline experiences and caching are the most common use cases for PWAs”
Your use case may be different. For example, you can allow your users to continue browsing your web page even when offline, as long as the information you provide on it is fairly static. In fact, offline experiences and caching are the most common use cases for PWAs. I point you to this MDN article again, it does a great job of covering the topic. But you should definitely learn caching strategies from The Offline Cookbook first.
Remember! Cache doesn't necessarily mean faster! The computer disk may be slower than the Internet connection. Use caching strategies wisely. Read The Offline Cookbook.
Best links that cover offline and cache experiences:
- Making PWAs work offline (MDN)
- Create an offline fallback page (Google)
- Managing fallback responses (Google)
- Make PWA Work Offline (Microsoft)
- The Offline Cookbook (Google)
- The Cache API: A quick guide (Google)
- Service workers and the Cache Storage API (Google)
- - (Apple)
Manifest
This is the file that tells the browser how your application should behave when you try to install it or when it is installed - read Google doc where you can see a link to the MDN's document on browser support for the manifest file, or read this spec.
“If you only have a service worker file, but no manifest, then it is perfectly fine if your use case is only about caching.”
Here you must understand one simple thing, as I again have seen some kind of misunderstanding. This file is not directly related to the service worker file. There will be no links in your code that will link these two files, you will not have a link from either the manifest to the service worker, or from the service worker to the manifest. If the browser sees only the manifest, then we tell the browser that we have a PWA to install, but the browser does not allow it to be installed, since there is no service worker. And if you only have a service worker file, but no manifest, then it is perfectly fine if your use case is only about caching - you won't be a PWA in that case, but the service worker will be registered by the browser and the browser will follow your instructions from the service worker file.
What is the content of the manifest file?
I won't cover this topic in great detail - the links above explain everything. There really aren't many things you should put in the manifest file. Remember that we are converting a web page (or web portal) into a PWA. Let's just say the manifest file contains the name of your web page and links to the icons. Well, you can always check the manifest file directly from the blog you're reading and install my blog as an app and see what stuff from the manifest file goes where. I highly recommend checking out my full guide on app icons here too.
How does the browser know about our manifest file?
We tell the browser where our manifest is located like this:
<link rel="manifest" href="/assets/backend/pwa/manifest-iot.json">We include this tag on every page that is part of the app - most of the time in the header template. As already mentioned, there is no connection between the manifest and the service worker in the code.
Prove it! Comment out the tag above and see what DevTools tells you. Given that your service worker file is written correctly, you will see that the service worker is registered and DevTools says "No manifest detected". And that's okay if your use case allows it - for example, you're only using it for caching strategies.
If you want the service worker to register on every page of your site and all pages are considered PWA, then you need to put "/" in the scope. In my article on PWA secrets, you will learn how to solve problems you may encounter in Lighthouse or DevTools reporting.
Install the App
I post useful information on my blog and share my experience for free. I don't post links to Amazon or anything like that. If my articles educated you, or maybe even helped you earn or save money or find a job, you can buy me a coffee.
Once you have the service worker and manifest correctly written, your application can be installed. A prompt to install your app will appear at the bottom of Chrome on Android, or in the address bar of Chrome or Edge on a Windows PC. Unfortunately, Safari on iPhone doesn't prompt to install your app. I covered the topic of installation in detail in my article on PWA behavior across platforms.
Here is a screenshot of 7 websites that I converted to PWA:
Example: my blog Denis.es
The blog you are reading is a PWA - install it on your phone and it will remind you of new useful articles. For my blog, I wrote a service worker file that supports the offline page and almost every possible caching strategy that can improve the performance of your site. I named it "Website Booster & Offline Denis.es Blog Service Worker". This file is well documented. You can read more about this in my article on PWA secrets and debugging.