Merge branch 'main' into staging

apps/blog/src/docs/android/android-playstore-documentation/android-playstore-documentation.md

@@ -0,0 +1,29 @@
+---
+layout: doc
+title: Android Platform
+excerpt: Publish your PWA to Google Play
+description: Publish your PWA to Google Play
+date: 2021-06-23
+updatedDate: 2021-10-27
+trending: false
+featured: true
+recommended: true
+isDocumentation: true
+backUrl: '/docs'
+image: docs/android/android-playstore-documentation/StoreLogo.png
+author:
+  name: PWA Builder documentation
+tags:
+  - docs
+  - Documentation
+  - Android
+---
+
+<img src="/docs/android/android-playstore-documentation/StoreLogo.png" style="max-height: 200px;" alt="Android Playstore Logo" />
+
+PWABuilder's Android platform utilizes the [open source Bubblerwrap tool](https://github.com/GoogleChromeLabs/bubblewrap) to generate a [Trusted Web Activity](https://developers.google.com/web/android/trusted-web-activity/) (TWA) that can be installed on the Google Play Store. This TWA behaves like any other Android application and is a great way to ship your PWA to the Google Play Store.
+
+1. [Generating your Android app with PWABuilder](/docs/generating-your-android-package)
+2. [Testing and publishing your your app to the Google Play Store](/docs/testing-and-publishing-your-android-pwa-to-the-google-play-store)
+3. [Updating your existing app](/docs/updating-your-existing-app)
+4. [Removing the Browser Address Bar: Asset Links](/docs/removing-the-browser-address-bar)

apps/blog/src/docs/android/generating-your-android-package/generating-your-android-package.md

@@ -0,0 +1,88 @@
+---
+layout: doc
+title: Generating your Android package
+excerpt: Everything you need to know about testing and generating your Android app with PWABuilder
+description: Everything you need to know about testing and generating your Android app with PWABuilderPlay Store
+date: 2021-09-17
+updatedDate: 2021-09-17
+trending: false
+featured: false
+isDocumentation: true
+backUrl: '/docs/android-platform-documentation/'
+image: docs/android/next-steps-documentation/StoreLogo.png
+author:
+  name: PWA Builder documentation
+tags:
+  - docs
+  - Documentation
+  - Android
+---
+
+To learn more about how PWABuilder generates a Trusted Web Activity from your PWA, check out [our post](/posts/microsoft-and-google-team-up) on this collaborative effort.
+
+## Generating your Android application with PWABuilder
+
+First, go to pwabuilder.com and put in the URL to your PWA, such as [https://sadchonks.com](https://sadchonks.com):
+
+![A screenshot of PWABuilder that shows where to enter your URL](/docs/android/generating-your-android-package/enter-url.png)
+
+and then tap start to analyze your PWA.
+
+![A screenshot of the analyzing page in PWABuilder analyzing a PWA.](/docs/android/generating-your-android-package/analyzing.png)
+
+You are now at the report card page! If your app is already a PWA your scores will all be green, if not, thats ok! You can [use PWABuilder to help convert your web app to a PWA](/docs/converting-your-web-app-to-a-progressive-web-app-with-pwabuilder/). You can now tap the next button to continue to the packaging page!
+
+![A screenshot of the report card page in PWABuilder. This PWA has great scores across the Manifest, Service Worker and Security](/docs/android/generating-your-android-package/report_card.png)
+
+You can now tap the Store Package button on the Android platform to generate your Android app.
+
+![A screenshot of the Android platform card on PWABuilder that shows the Store Package button](/docs/android/generating-your-android-package/android-card.png)
+
+Next you will see a list of the different options for the Android platform that are covered in more detail below.
+
+![A screenshot of the Android platform options UI in PWABuilder. This UI enables you to edit many details of your Android application](/docs/android/generating-your-android-package/options.png)
+
+When you are ready, tap the Generate button to generate your Android app, and then the Download button when it pops up to download the generated App and associated files.
+
+![A screenshot of the Download button on PWABuilder. You can tap this button to download your generated app](/docs/android/generating-your-android-package/download.png)
+
+After generating your Android app, see our [Android Next Steps documentation](/docs/android/next-steps-documentation/) for more information on how to test your application and then publish to the Google Play Store!
+
+## Android Features & Customization
+
+When we rolled out our initial collaborative work with Google’s Bubblewrap this spring, PWABuilder didn’t have a way to customize the Android package it generated. While this was fine for some basic scenarios, like publishing to the Google Play Store for the first time, it fell short in other ways.
+
+To address this, we’ve updated PWABuilder to allow for full customization of your Android app package
+
+With this new functionality, you can customize your PWA for Android:
+
+- **Package ID:** The Android identifier unique to your app
+- **App name:** The full name of your app. We prepopulate this with the [app name](https://w3c.github.io/manifest/#name-member) from your PWA’s app manifest.
+- **Launcher name**: The name of your app in the Android launcher. This is typically the same as app name, or a shortened version of it. We prepopulate this with [short_name](https://w3c.github.io/manifest/#short_name-member) from your PWA’s app manifest.
+- **App version**: This is the version string displayed to end users, e.g. "1.0.0.0"
+- **App version code**: This is an integer used as a private, internal version of your app.
+- **Host, Start URL, Manifest URL**: The URLs used to launch your PWA in the Android app. We prepopulate these for you from your app manifest.
+- **Status bar color, Nav bar color**: The color of the Android status bar and navigation bar in your PWA. You can also hide these bars by setting Display to
+  Fullscreen. We prepopulate this using colors from your app manifest.
+- **Nav bar color:** Same as above, but for the Android navigation bar. Also can be hidden by setting Display to Fullscreen.
+- **Splash screen color:** The background color of the splash screen that will be used when creating your Android app. We prepopulate this with the theme color
+  specified in your app manifest.
+- **Splash screen fade out time:** How long to fade out the splash screen in milliseconds. We default to 300ms.
+- **Icon URL**: URLs for the icon to use for your app. We recommend a 512x512 icon.
+- **Maskable icon URL**: Optional. The icon to use on Android devices that show rounded corner icons. Typically, this icon should have some padding around the
+  icon’s content, enabling the icon to be safely rounded without losing fidelity. We populate this with a [purpose: maskable](https://w3c.github.io/manifest/#purpose-member icon from your app manifest. If one can’t be found, we use the icon. For more information about
+  maskable icons on Android, see [https://web.dev/maskable-icon](https://web.dev/maskable-icon/).
+- **Monochrome icon URL**: Optional. The monochrome icon to use for your app. Android can use this to fill your icon with a certain color based on user preferences, theme or color mode, or high contrast configurations. We populate this with a [purpose: monochrome](https://w3c.github.io/manifest/#purpose-member) icon from your app manifest.
+- **Fallback behavior:** When the full TWA experience isn’t available, how should your app proceed, whether with a web view or [Chrome’s Custom Tabs feature](https://developer.chrome.com/multidevice/android/customtabs). We default to the latter.
+- **Display mode:** <br> **— Standalone** means your PWA takes up all the area except Android status bar and Navigation bar. <br> **— Fullscreen** hide both
+  bars. This is intended for immersive experiences likes games and media playback.
+- **Notifications**: If enabled, your PWA will use [Android Notification Delegation](https://github.com/GoogleChromeLabs/svgomg-twa/issues/60) for push
+  notifications, meaning your installed PWA can send push notifications without browser permission prompts. You should enable this if your PWA sends push
+  notifications.
+- **Signing key:** How the APK app package will be digitally signed: <br> **— None:** your app package won’t be signed. Unsigned packages will be signed by
+  the Google Play Store. This is Google’s recommendation, and our default.<br> **— New:** PWABuilder will create a new signing key for you. The signing key will
+  be included in your zip download. Choosing this will let you fill in details like password, alias, and more.<br> **— Mine:** Upload an existing .keystore
+  file to use for signing the app package. This should be used if you are updating an existing app in the Store. You’ll be prompted to specify your existing key
+  passwords and alias.
+
+Whew! As you can see, you can customize nearly every aspect of your PWA Android app package.

apps/blog/src/docs/android/next-steps-documentation/next-steps-documentation.md

@@ -0,0 +1,123 @@
+---
+layout: doc
+title: Testing and publishing your Android PWA to the Google Play Store
+excerpt: Everything you need to know about testing and publishing your Android PWA to the Google Play Store
+description: Everything you need to know about testing and publishing your Android PWA to the Google Play Store
+date: 2021-09-17
+updatedDate: 2021-09-17
+trending: false
+featured: false
+isDocumentation: true
+backUrl: '/docs/android-platform-documentation/'
+author:
+  name: PWA Builder documentation
+tags:
+  - docs
+  - Documentation
+  - Android
+  - PlayStore
+---
+
+# Testing and publishing your Android PWA to the Google Play Store
+
+First, to generate your Android package with [PWABuilder](https://www.pwabuilder.com)
+
+Your next steps:
+1. **Deploy `assetlinks.json` to your server** to prove domain ownership.
+2. **Test your app**: open the `.apk` file on an Android device or Android emulator.
+3. **Submit your app to Google Play**: upload the `.aab` file to the Google Play Store.
+4. **Update `assetlinks.json` for production**: after Google Play signs your app, you'll need to update your asset links to remove the address bar from your app.
+
+Each step is explained below.
+
+## 1. Deploy `assetlinks.json`
+
+Your zip file contains `assetlinks.json`. This is a [digital asset links file](https://developers.google.com/web/updates/2019/08/twas-quickstart#creating-your-asset-link-file) that proves ownership of your PWA. Upload this file to your server at `https://example.com/.well-known/assetlinks.json`. (Replace example.com with your PWA's URL.)
+
+> 💁‍♂️ *Heads up*: 
+> 
+> **Digital asset links are required for your PWA on Android**. If you're seeing a browser address bar in your app on Android, or if your app is crashing on launch, it means your `assetlinks.json` file is missing, inaccessible, or incorrect. See our [asset links helper](/Asset-links.md) to fix this.
+
+## 2. Test your app on an Android device or Android emulator
+Your zip file contains an `.apk` (Android Package) file, which can be loaded on your personal Android device or Android emulator.
+
+**To test your app, install open the `.apk` file on your Android device or emulator.**
+
+If you don't have a physical Android device, you can use an Android emulator such as the free [Android Emulator included in Android Studio](https://developer.android.com/studio/run/emulator). Run the emulator and open the `.apk` file to install your app. You can also drag and drop the `.apk` file onto the Android emulator to install it.
+
+## 3. Upload your app to the Google Play Store
+
+Your zip file contains an `.aab` (Android App Bundle) file which can be submitted directly to the Play Store through the [Google Play Console](https://developer.android.com/distribute/console).
+
+Once you submit your app, it will be reviewed. Once approved, your PWA will be available in the Google Play Store. 😎
+
+## 4. Update your asset links file for production
+
+> 💁🏽‍♀️ *Heads up*: 
+> 
+> This step is required for running the production version of your app. If you skip this step, your app will crash or will a browser address bar will appear inside your app. See our [asset links helper](/Asset-links.md#validate-your-assetlinksjson-file) for more info.
+
+Once you've uploaded your `.aab` file, Google Play re-signs your app. Because of this, you'll need to update your asset links file.
+
+To update your asset links and remove the address bar from your app, login to the [Google Play Console](https://developer.android.com/distribute/console), select your app, then choose `Setup` -> `App integrity`, then copy your `SHA-256 fingerprint`:
+
+<img src="/static/google-play-signing.png" alt="Google Play Console screenshot with App Signing flow" width="600px" />
+
+Then, paste the fingerprint into your `assetlinks.json` file:
+
+```json
+[
+    {
+        "relation": ...,
+        "target": {
+            "namespace": ...,
+            "package_name": ...,
+            "sha256_cert_fingerprints": [
+                "...",
+                "PASTE YOUR NEW SHA-256 FINGERPRINT HERE"
+            ]
+        }
+    }
+]
+```
+
+Once your updated `assetlinks.json` file is deployed to your server, the address bar will disappear from your app.
+
+## Save your signing key
+
+Your zip file contains `signing.keystore` and `signing-key-info.txt`:
+
+- `signing.keystore` is the Android key store file containing the signing key.
+- `signing-key-info.txt` is a text file containing your signing key information, such as the key password, store password, and key alias.
+
+Keep both of these files in a safe place. **You'll need them to deploy future versions of your app.** See [Uploading a new version](#uploading-a-new-version) for more info.
+
+## Updating an existing app in the Play Store
+
+Have an existing app in the Play Store and want to update it to a new version? No problem! See [updating an existing app](/docs/android/updating-your-existing-app).
+
+## Note about Quality Criteria on Android
+
+As of Chrome 86, PWAs downloaded from the Google Play Store will now crash if your app:
+- Does not have a valid TLS certificate
+- Does not link to your digital assetlinks file correctly
+
+Because of this you should ensure that your PWA runs on an HTTPS domain and has your assetlinks file properly linked.
+
+For more info about Chrome's quality criteria policy, check out [this article](https://blog.chromium.org/2020/06/changes-to-quality-criteria-for-pwas.html) from our friends over on the Chrome team.
+
+## Note about Apps for Children
+
+Be aware that PWAs on Android cannot currently target children as their audience.
+
+Google Play's [Children And Families Policy](https://developer.android.com/google-play/guides/families) blocks PWAs from targetting children because PWAs potentially have full access to the web.
+
+If you're building an education app, for example, you'll need to specify `Target Audience: Older Users` when submitting your app to Google Play. Otherwise your app may not be approved, or may be removed from the Store.
+
+Google is considering engineering and policy updates to permit PWAs for children in the future. Please see [this thread](https://github.com/pwa-builder/PWABuilder/issues/1752) for more details.
+
+## Need more help?
+
+If the browser address bar is showing up in your app, see our [asset links helper](https://github.com/pwa-builder/CloudAPK/blob/master/Asset-links.md).
+
+If you're otherwise stuck, we're here to help. You can [open an issue](https://github.com/pwa-builder/pwabuilder/issues) and we'll help walk you through it.