Home
Everything the app is doing for this store, at a glance.
Installs
Counted on your storefront. Days run midnight to midnight UTC.
Two things to do by hand
Neither can be done from here — both live in the theme, which this app has no permission to edit.
- Turn on the Storefront PWA app embed in Theme editor › App embeds. Nothing else has any effect until that is on.
- Then open
/apps/pwa/checkon your storefront to confirm the manifest, the icons and the install path on a real page.
The Quick setup wizard checks both of these against your live storefront and tells you which one is missing.
Where to go
What each page changes.
| Configuration | The app's name, icon and colors — what a customer sees on their home screen. |
| Install message | The card that invites customers to install, and what it says. |
| Cache assets | What the service worker keeps, and the list it fetches ahead of time. |
| Offline page | What a customer sees with no connection. |
| Settings | Launch behaviour, shortcuts, iOS, screenshots, and the master switch. |
| Reports | Page speed and installability, measured against the live store. |
Configuration
How your store looks as an installed app — its name, its icon and the colors it launches in.
Home screen
What the app is called once it is installed.
Logo
One square PNG, at least 512×512. Every size the manifest needs is generated from it, including the Android maskable pair. Until you upload one, a placeholder with your initial is used so the store is still installable.
Splash screen
The window a customer sees before your storefront has painted.
A sketch, not a render. Wallpaper and icon corners are the device's, not yours.
Install message
The card that invites a customer to install. Where the browser allows it, the button opens the native install dialog; everywhere else it shows that browser's own directions.
Header
Benefits
Up to 5 short lines, shown as bullets above the message. 30 characters each — longer than that and the card grows tall enough to cover the page it is sitting on. Leave them all empty for a compact card.
Message
Button
When it appears
You can also add data-pwa-install to any element in your theme — a nav link, a footer button — and it will open the same prompt.
Cache assets
What the service worker keeps a copy of, so a returning customer downloads less.
Cache
Reduce the time it takes to move from page to page by keeping your Shopify assets — CSS, images, Google Fonts — instead of fetching them on every visit.
Carts, checkouts, accounts and search are never cached, whatever is ticked here. A stale price or a stale cart is worse than a slow one.
Precache
A list of specific files to fetch into the cache the first time a customer visits, rather than the first time each one is needed. Up to 40. Every entry is a download that first visit pays for, so keep it to the files every page uses.
/cdn/shop/t/1/assets/base.css) or full URLs on cdn.shopify.com or Google Fonts. Anything else is dropped when you save.Not seeing your changes?
Saving is instant here, but four different caches sit between this screen and a customer's phone. This forces the two that can be forced.
| App icon, launch screens | Refreshed now. Every image gets a new address, so nothing can serve the old one. |
| Service worker cache | Cleared on each visitor's next page view. The new worker deletes the old cache when it takes over. |
| Manifest and storefront script | Expire on their own within 5 and 10 minutes. Shopify has no way to purge these early, so no button can. |
| Apps already on a home screen | Keep the name and icon captured when they were installed. Android may pick up a change eventually; iOS needs a reinstall. |
Offline page
What a customer sees when the connection drops. Served from the cache, so it appears even when nothing else can load.
The page carries a Try again button and reloads by itself the moment the connection returns, so neither needs saying here. Your wording is also used by the launch screen when the installed app is opened with no connection.
Where it comes from
Turning this off stops the page being precached, so a customer with no connection gets the browser's own error instead. It costs one small HTML file per visitor, which is why it is on by default. Changing the wording bumps the cache version, so returning visitors pick it up on their next page view.
Preview
Offline browsing
Let customers open pages they have already visited with no connection — product pages, collections, the home page.
Status
Checking your storefront…
Why this needs one extra step
A service worker only controls pages below the folder it is served from. Through Shopify it can only be served from /apps/pwa/, and Shopify strips the header that would widen it — so it never sees a product page. Served from /sw.js on your own domain it controls every page. Shopify cannot serve that file; something in front of your store has to. The storefront script detects it by itself the moment it is there — nothing to save here afterwards.
Set it up with Cloudflare — one click
For a store whose domain is on Cloudflare with the orange cloud (proxied) on its Shopify record. This uploads a small Worker and routes only /sw.js to it — nothing else on your storefront goes through it.
- In Cloudflare open My Profile › API Tokens › Create Token › Custom token.
- Permissions:
Account › Workers Scripts › Edit,Zone › Workers Routes › Edit,Zone › Zone › Read, and optionallyZone › DNS › Readso the app can warn you about a grey-cloud record. - Limit it to your store's zone, create it, and paste it below.
The token is used for this one request and never saved. You can delete it in Cloudflare as soon as this finishes; running this again later needs a new one.
Or set it up by hand
The same thing, to paste yourself. Each one serves this app's worker at /sw.js with the X-PWA-Root-Worker header the storefront looks for.
Cloudflare Worker (manual)
Workers & Pages › Create › Hello World › Edit code, replace everything with this, Deploy. Then Settings › Domains & Routes › Add route yourstore.com/sw.js.
nginx (your own reverse proxy)
Only if your domain already points at an nginx you run in front of Shopify. Goes inside that server { } block.
Apache .htaccess (your own reverse proxy)
Only if Apache serves your domain and proxies it to Shopify. A store hosted by Shopify never reads an .htaccess.
What gets cached
Pages are fetched from the network first and only served from the cache when there is no connection, so a customer online always sees live prices and stock. Carts, checkout and accounts are never cached. Which page types are kept is set on Cache assets.
Settings
Launch behaviour, shortcuts, iOS, install-dialog screenshots — and the switch that turns the whole thing off.
Status
Two switches control this app, and they do different jobs. The theme app embed decides whether the tags are on the page at all — that is a theme change, made in the theme editor. The switch below leaves the theme alone and makes the manifest non-installable, which is the one to reach for if something looks wrong on a live store.
Launch behaviour
Where the app opens, and which pages count as part of it.
/ is almost always right.Shortcuts
Up to four. Long-press the icon on Android, right-click it on desktop.
Language and listing
en, ur, ar-AE.iOS
Safari ignores most of the manifest and uses its own tags, so these are separate settings rather than duplicates.
Install dialog screenshots
Optional. With a screenshot present, Chrome shows a larger install dialog with a preview instead of a plain one-line prompt.
Wide (desktop)
Landscape, e.g. 1280×800.
Narrow (mobile)
Portrait, e.g. 750×1334.
Service worker
Registers a worker on your storefront. On a stock Shopify store its scope stays /apps/pwa/, which is enough to make a cold offline launch land on the app shell and not enough to serve your catalogue. Installing does not depend on it.
PWA / Performance reports
Page speed measured by Google PageSpeed Insights, and installability measured by this app against your live storefront.
A run takes up to a minute — PageSpeed loads your store on a throttled connection, which is the point of it.
History
The most recent runs. Older ones drop off the bottom.
Analytics
Installs and dismissals, split by device. Counted on your storefront — nothing about the customer is recorded.
App installed
App dismissed
A customer who was shown the card and said no. The corner × is not counted — that one means "not on this screen", and the card comes back on the next page view.
Total app installed
The funnel
Every step from "the card appeared" to "the app was opened again".
Quick setup wizard
The same checks a report scores you on, run against your live storefront.
Not run yet.
FAQs
The questions this app actually gets asked.
Why does my store need the app embed turned on?
The embed is what puts this app's two tags on your storefront pages. Without it there is no manifest link and no script, so no browser has any idea the store is installable. It lives in Theme editor › App embeds because adding tags to a theme is a theme change, and this app has no permission to edit your theme.
Why can't my customers browse offline?
A service worker may only control pages below the folder it is served from. Widening that needs a Service-Worker-Allowed header, and Shopify strips that header when it proxies /apps/pwa/. So the worker's scope stays /apps/pwa/ and it never sees a product page. The fix is to serve the worker at /sw.js on your own domain, which needs something in front of Shopify — the Offline browsing page sets that up on Cloudflare in one click, or gives you the config to paste.
Why is my iOS install count lower than I expected?
Safari has no install event of any kind. An iOS install is invisible until the app is first opened, and it is counted then. A customer who adds the app to their home screen and does not open it for a week appears a week late.
I changed the name and icon. Why does my phone still show the old one?
An installed app keeps the name and icon it captured at install time. Android may pick up a change eventually; iOS needs the app removed and added again. For customers who have not installed yet, Force a refresh on the Cache assets page moves every image URL at once.
What does the PWA score actually measure?
Ours, not Google's — Lighthouse dropped its PWA category in 2024. It is the share of the installability conditions this app is responsible for that your live storefront currently meets: the manifest reachable through the proxy, the icon sizes Chrome insists on, the embed on the page. The Quick setup wizard lists them one by one.
Does any of this track my customers?
No. The storefront script sends five counters — shown, clicked, dismissed, installed, launched — with the device family and nothing else. No IP, no user agent, no customer, no session is stored or derivable from the file. The counters live in one small JSON file per store and are deleted when the app is uninstalled.
Why are there two ways to turn the app off?
They do different things. The app embed decides whether the tags are on the page at all, and turning it off is a theme change. The switch on the Settings page leaves the theme alone and makes the manifest non-installable, which takes two seconds and is the one to reach for when something looks wrong on a live store.
Do I need a PageSpeed API key?
Not to start. Without one the app uses Google's unauthenticated quota, which is fine for the occasional run and will start refusing if you lean on it. Set PAGESPEED_API_KEY on the server to use your own.