Publish a Progressive Web App to the Microsoft Store
Publishing your Progressive Web App (PWA) to the Microsoft Store brings the following advantages:
|Discoverability||Users naturally look for apps in the app store. When you publish to the Microsoft Store, millions of Windows users can discover your PWA alongside other Windows apps. The Store showcases apps through categories, curated collections, and more. App discovery portals provide an easy browsing and shopping experience for potential users of your app. You can even enhance your Store listing with screenshots, a hero image, and video trailers - see App screenshots, images, and trailers.|
|Trustworthiness||Windows customers know they can trust their Microsoft Store purchases and downloads, because they adhere to the rigorous Microsoft quality and safety standards.|
|Easy install||The Microsoft Store provides a consistent and user-friendly install experience across all Windows 10 or later apps.|
|App analytics||The Microsoft Partner Center dashboard provides detailed analytics about your app's health, usage, and more.|
To publish your PWA to the Microsoft Store, no code changes are required. Instead, you create an app reservation, package your PWA, and submit your package to the Store. The following sections explain the steps.
Create an app reservation
To submit your app to the Microsoft Store, you use Microsoft Partner Center.
To create an app reservation:
Before you can create an app reservation, you must have a personal Microsoft account (not a work Microsoft account or a school Microsoft account) that is enrolled in the Windows Developer Program.
Once your account is enrolled in the app developer program, follow these steps to create an app reservation:
- Go to the Partner Center Dashboard. Sign in with the account you enrolled.
- Under Workspaces, select Apps and games. The Apps and games | Overview page appears.
- Select New product > MSIX or PWA app.
- When prompted, enter a name for your reservation, and then select Reserve product name.
To display your publisher details for use in the Package your PWA section, select Product management > Product Identity.
Copy and save the following values.
- Package ID
- Publisher ID
- Publisher display name
Package your PWA for the Store
Now that you have your app publishing information, generate a Windows app package for your PWA.
To generate an app package:
Go to PWA Builder.
Under Ship your PWA to app stores, enter the URL of your PWA in the text box, and then click the Start button.
Your PWA is evaluated to ensure it is store-ready.
If the evaluation in the PWABuilder report card page indicates that your PWA is ready to be packaged, continue to the next step. If the evaluation indicates that your PWA is not ready to be packaged, examine the Action Items section to see how to improve your PWA:
Once your PWA is ready to be packaged, in the upper-right corner of the PWABuilder report card page, click the Package For Stores button.
Under Windows, click the Generate Package button.
Paste the following values, which you saved in the Create an app reservation section above:
- Package ID
- Publisher display name
- Publisher ID
Click the Download Package button to download your Windows package.
Your download is a
.zip archive that contains an
.msixbundle file and a
.classic.appxbundle file. The two app packages allow your PWA to run on a wide variety of Windows versions. For more information, see What is a classic package?
Submit your app package to the Store
To submit your app to the Microsoft Store:
Go to Microsoft Partner Center.
Select your app.
Click the Start your submission button.
When you're prompted, provide information about your app, such as pricing and age rating.
On the Packages prompt, select the
.classic.appxbundlefiles you generated in the Package your PWA section.
After you complete your submission, your app is reviewed, typically within 24 to 48 hours. After you receive approval, your PWA is available in the Microsoft Store.
Measure usage of your PWA installed from the Microsoft Store
When your PWA is initially launched, if the PWA was installed from the Microsoft Store, Microsoft Edge includes the following
Referer header with the request of the first navigation of your web app.
Use this feature to measure distinct traffic from your PWA that was installed from the Microsoft Store. Based on the traffic, you can adjust your app's content to improve the user experience. This feature is accessible to both client and server code. To access this information on the client side, you can query
Redirect to locale-specific domains without displaying additional UI
By default, a PWA that's installed from the Microsoft Store displays an additional UI when the app is redirected to a locale-specific domain. The added UI shows the URL and page title. This UI is added because navigation to the locale-specific domain is considered "out-of-scope". However, you can prevent this UI from being displayed, by specifying locale-specific origins that are associated with the PWA.
The following figure shows the UI that is introduced when a user moves outside the scope of a PWA.
Domain redirection with browser-installed PWAs
A Web App Manifest is tied to a single domain. However, some PWAs use locale-specific domains for their customers in specific regions of the globe. When visiting the PWA in a web browser, customers are seamlessly transitioned from the principal domain (for example, contoso.com) to a locale-specific domain (for example, contoso.co.ke), because the redirect happens during initial load of that website.
Customers who install the PWA from Microsoft Edge would therefore install the PWA from the locale-specific domain. Subsequent launches of the PWA go directly to that locale-specific domain, instead of first going to the principal domain.
Domain redirection with PWAs installed from the Microsoft Store
PWAs that are installed from the Microsoft Store have a hard-coded start URL that is pointed at the principal domain. When the PWA is launched, the PWA initially navigates to the principal domain, and then a customer may (as necessary) be redirected to their locale-specific domain. If that redirection occurs, the navigation is considered "out of scope". As a result, the app displays the URL and page title at the top of the page.
Displaying the URL and page title is a security feature to ensure that users know they have left the context of the PWA. This added UI makes sense when a user loads a page from another website in the context of the PWA. However, that added UI may be inappropriate when a user moves among domains that are all part of the same website.
Prevent the locale-specific URL and title from being displayed
To prevent the additional UI from being shown in a PWA that's installed from the Microsoft Store, you can use URL Handlers to enable the PWA to span multiple locale-specific domains.
To prevent displaying the URL and page title:
- Within the PWA's Web App Manifest, use the
url_handlersmember to specify an array of origins that are associated with that app.
- On each of the referenced origins, include a
web-app-origin-associationfile that associates the PWA with that domain.
When these domain lists are in place, Microsoft Edge no longer shows the additional UI when the principal domain is redirected to the locale-specific domains.
url_handlers feature will be replaced by
scope_extensions, but that spec is still in development.
scope_extensions will produce the same result as