Android Concepts (for Web Developers)

If you're a Web developer who is new to Android and Google Play, there are some details you should be aware of. There already exist many resources and documentation for this (thanks to the Android team) but here we'll highlight some important concepts and how they relate to Bubblewrap.

# Upload vs. Signing Key

If you plan to use Bubblewrap to generate an Android App Bundle (AAB) (Note: Starting in August 2021, Google Play will require all new apps to use the Android App Bundle format) or APK to upload and publish to Google Play, you'll need to sign your app with a signing key. Google Play gives you two options for how you can handle this:

• Play App Signing (highly recommended): Google will manage and protect your app's signing key for you. It uses it to sign your APKs for distribution. Play App Signing uses two keys. The "app signing key" which Google will manage for you and the "upload key" which you keep and should stay private to you. You use the upload key to sign your app for uploading to the Play Console. This system makes it possible for you to reset your upload key if it ever gets lost or compromised, by contacting the Play support team. Currently, Google Play lets you upload your app as an AAB or APK:
  • Android App Bundle (AAB): When you upload an AAB to the Play Console, you defer the building and generation of APKs to the Google Play Store. When a user downloads and installs your app, Google Play will distribute it to them as a signed APK. Therefore, the signing of the APKs will also need to be done by Google Play. So, by default, if you upload your app as an AAB to the Play Console, it will require you to use Play App Signing.
  • APK: With APKs, you have the choice to opt in to Play App Signing. Opting in to Play App Signing is highly recommended because it increases the security of your signing key. As noted before, Google Play will soon require all new apps be uploaded in the AAB format, so we recommend doing that instead of uploading APKs.
• Manage your own signing key: If you choose to manage your own key and not opt in to Play App Signing, you are fully responsible for your app's signing key. Unlike with Play App Signing, it is not possible to reset it if you lose the key. Therefore, losing your app's signing key means you also lose the ability to update your app.

During the bubblewrap init setup, when you get to the "Signing key information (5/5)" portion, you'll be prompted to enter a "Key store location" and "Key name", or use the defaults. The default key store location is the file android.keystore in your project directory and the default key name is android. If Bubblewrap doesn't find an existing keystore with that key name at the location, it will create one for you and also prompt you for passwords. Take note of the passwords you entered as you'll need them during the build process (bubblewrap build) where it will use the key to sign your app. If you opt in to Play App Signing, then the signing key that Bubblewrap generated and used to sign your app becomes the "upload key". Whether you choose to use the Bubblewrap generated key as your signing or upload key, you should guard and keep the key private. We don't recommend committing it to version control. Instead, limit the number of individuals with access to it.

# Digital Asset Links

Digital Asset Links are needed to declare the relationship between your website and your Android app. To ensure that your Android app generated by Bubblewrap is verified properly and launches as a Trusted Web Activity (instead of a Chrome Custom Tab), you'll need to add the appropriate key to your assetlinks.json file. Then upload it to your website at .well-known/assetlinks.json (relative to the root). Your assetlinks.json file should follow this format:

[{
 "relation": ["delegate_permission/common.handle_all_urls"],
 "target": {
   "namespace": "android_app",
   "package_name": "com.your.package_name",
   "sha256_cert_fingerprints": [
     "XX:XX:XX:..."
   ]
 }
}]

# Get the SHA256 certificate fingerprint

To create the assetlinks.json file, you'll need the SHA 256 certificate fingerprint associated with your app's signing key. The important thing to note is that the fingerprints associated with your signing and upload keys will be different. It's important to keep this distinction in mind, especially if you observe your app launching as a Chrome Custom Tab (with the browser bar visible). Then, it's likely your assetlinks.json file does not have the fingerprint that corresponds to the appropriate key.

It's useful to have both your signing and upload certificate's fingerprint in your assetlinks.json to more easily debug your app locally. See Adding More Keys below for more information on how to have both keys in the assetlinks.json file.

There are a couple of different ways to get the fingerprint which are detailed in the next sections. They should all give you the same fingerprints so feel free to choose the method that is most convenient.

# Via Play Console

Depending on if you opt in to Play App Signing or not, you may have one or two keys. To retrieve the appropriate SHA256 fingerprint for each key:

1. Go to the Play Console
2. Select the app you're interested in
3. In the navigation menu on the left, under Release, go to Setup -> App Integrity.
4. Copy the SHA256 for the appropriate key:

• Signing key: Copy the SHA256 fingerprint for the "App signing key certificate". This fingerprint will correspond to your app if you download it from the Google Play Store since Google Play distributes your app signed with the signing key.

• Upload key: Copy the SHA256 fingerprint for the "Upload key certificate". This fingerprint will correspond to your app if you install it locally (via ADB over USB for example). That APK (on your local machine) was built by Bubblewrap, and therefore, signed by the key it created for you as well (during the init setup). Remember that this may be the signing key for your locally installed app, but this actually becomes the "upload key" once you publish your app through Play.

# Via keytool

keytool is a key and certificate management tool. You can use keytool to extract the SHA 256 fingerprint associated with the APK or AAB Bubblewrap generated. Note that this fingerprint is for the local signing key and if you upload your app to Play and opt in to Play App Signing, this key becomes the "upload key".

keytool -printcert -jarfile [path to APK or AAB] | grep SHA256

# Via Asset Link Tool

Another way to get the correct Digital Asset Links file for your app, is to use the Asset Link Tool:

1. Install the Asset Link Tool from the Play Store.
2. On the same device, download your app from the Google Play Store or install it locally.
3. Open the Asset Link Tool app, and you'll be given a list of all applications installed on your device by package name. Filter the list by the application ID you chose earlier during bubblewrap init and click on that entry.
4. You'll see a page listing your app's signature and a generated Digital Asset Link. Click on the Copy or Share buttons at the bottom to export it however you like (e.g., save to Google Keep, email it to yourself).

The same idea applies as before with signing or upload keys. If you installed your app from the Google Play Store, the Asset Link Tool will get you the fingerprint for your app's signing key. If you installed the app directly from your local machine, then the fingerprint is for the key Bubblewrap generated.

# Ensuring your asset link file is accessible

Now that you've uploaded it, make sure you can access your asset link file in a browser. Check that https://example.com/.well-known/assetlinks.json resolves to the file you just uploaded.

# Jekyll based websites

If your website is generated by Jekyll (such as GitHub Pages), you'll need to add a line of configuration so that the .well-known directory is included in the output. GitHub help has more information on this topic. Create a file called _config.yml at the root of your site (or add to it if it already exists) and enter:

# Folders with dotfiles are ignored by default.
include: [.well-known]

# Adding more keys

A Digital Asset Link file can contain more than one app, and for each app, it can contain more than one key. For example, to add a second key, just use the Asset Link Tool to determine the key and add it as a second entry. The code in Chrome that parses this JSON is quite strict, so make sure you don't accidentally add an extra comma at the end of the list.

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.your.package_name",
    "sha256_cert_fingerprints": [
      "XX:XX:XX:..."
    ]
  }
},{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.your.package_name",
    "sha256_cert_fingerprints": [
      "XX:XX:XX:..."
    ]
  }
}]

# Troubleshooting

Chrome logs the reason that Digital Asset Links verification fails and you can view the logs on an Android device with adb logcat. If you're developing on Linux/Mac, you can see the relevant logs from a connected device with:

> adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links

For example, if you see the message Statement failure matching fingerprint., you should use the Asset Link Tool to see your app's signature and make sure it matches that in your assetlinks.json file.