[Site cannot be installed: the page does not work offline 📶] Fix the Problem to Prompt the Add to Home Screen Message
Last Updated -
Are you seeing an error in the console: "Site cannot be installed: the page does not work offline". Or maybe your PWA is not triggering the Chrome add to homescreen prompt or is it just not working for you? This may be your solution.
Progressive web applications are an exciting new way to level up your website and engage customers at a deeper level. The key is triggering the browser to prompt the customer to add your PWA to their home screen.
But why is your PWA not triggering the Add to Homescreen prompt?
Many companies are upgrading their websites to progressive web applications in hopes customers will add their PWA to the homescreen and take that crucial step to a closer relationship between business and customer. Upgrading to a progressive web application is simple enough: serve your site via HTTPS, reference a valid web manifest file and register a service worker with a fetch event handler.
However, I see questions every week from developers asking why their site is not triggering the Add to Homescreen prompt.
How can you solve the missing add to homescreen problem?
The first place you should check is the browser console. You can trigger this by pressing F12 or Ctrl + Shift + I. This opens the browser developer tools. Find the console tab so you can see the messages logged from your code and the browser. Chances are if your site is failing to trigger the add to home screen prompt you will identify the problem there.
Failing to Serve Via HTTPS
Properly service a site via HTTPS requires more than just installing a valid SSL/TLS certificate. You must also reference all external assets and resources via HTTPS. This means any internal JavaScript, CSS fonts and images as well as any third party assets. You should also convert any links to other URLs to HTTPS.
The best way to ensure this happens is to do a global search and replace in your source code for http:// and replace them with //. When you use a protocoless reference the browser automatically uses the protocol used to load the HTML document.
Of course this is a simplified way to update your site. It is important you perform a thorough audit of your site's pages to ensure everything is securely referenced. Third party scripts may be the source of your issue because they often reference 4th, 5th and additional levels scripts, which are completely out of your control.
Missing or Invalid Web Manifest File
All progressive web applications must reference a valid web manifest file. The web manifest file is a simple JSON document containing a few meta properties that describe the website to the browser. This includes a name and a minimal array of images icons. These icons are used for the homescreen icon and a potential splash screen.
You can add a validation step to your build by including a step to execute the nodejs web manifest validator (https://www.npmjs.com/package/web-app-manifest-validator).
Missing or Failed Service Worker
If HTTPS and web manifest is not your issue your service worker is failing.
Chrome has quietly increased the service worker requirement by checking to see if the service worker registers a fetch event handler. Often when a site first upgrades to a progressive web application a service worker is registered and deployed. However, to test if the add to homescreen prompt is triggered the initial service worker does not register a fetch event handler.
Chrome looks for the fetch event handler as a minimal test for offline capability. Designing a proper caching strategy is not simple, so deploying an 'empty' or placeholder service worker is a valid strategy to get started. Just make sure you have a fetch event handler.
If you have a fetch event handler, but are still failing to trigger the prompt the next place I check is registration exceptions. If the service worker fails to register the site is not considered a valid progressive web application.
There are many reasons why the service worker fails to register. Failing to deploy the file results in a 404 status, so make sure your deploy script includes your service worker.
If the install event handler throws an exception the service worker registration fails. The most common reason the install event handler fails is trying to pre-cache a URL that does not exist (404). If caching any file fails, a 4xx or 5xx status code are the primary reasons, an exception is throw by the CACHE API and the event fails.
Don't Be Discouraged
These are common issues new service worker developer and site owners encounter. They are all easy to troubleshoot and resolve. Always check the browser's developer console to see any error messages the browser echoed.
Progressive Web App Training and Examples
Still not sure how to upgrade your existing site to a progressive web app? No worries, feel free to contact Love2Dev. We would love to get your started and help you unlock the best way to engage with customers.
Do you want a much more detailed set of progressive web app and service worker tutorials? I just launched a new course, Progressive Web Apps : From Beginner to Expert.
This course covers everything you need to know to make any website a progressive web application. There are beginner topics to help anyone get started with progressive web app and service worker development. There are also modules to teach you how to polyfil many modern PWA features like offline and add to homescreen tactics.
Enroll today and save $171 off the $200 price. Progressive Web Apps : From Beginner to Expert is only $29.