Peter Conn

Joyce Toh

If you're a Web developer who is new to Android and Google Play, there are some details you shouldbe aware of. There already exist many resources and documentation for this (thanks to the Androidteam) 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 August2021,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. GooglePlay gives you two options for how you can handle this:

• Play App Signing (highly recommended): Google will manage and protect your app's signing keyfor you. It uses it to sign your APKs for distribution. Play App Signing uses two keys. The "appsigning key" which Google will manage for you and the "upload key" which you keep and should stayprivate to you. You use the upload key to sign your app for uploading to the Play Console. Thissystem makes it possible for you to reset your upload key if it ever gets lost or compromised, bycontacting the Play support team. Currently, Google Playlets you upload your app as an AAB or APK:
  • Android App Bundle (AAB): Whenyou upload an AAB to the Play Console, you defer the building and generation of APKs to theGoogle Play Store. When a user downloads and installs your app, Google Play will distribute itto them as a signed APK. Therefore, the signing of the APKs will also need to be done byGoogle Play. So, by default, if you upload your app as an AAB to the Play Console, it willrequire you to use Play App Signing.
  • APK: With APKs, you have the choice to opt in to Play App Signing. Opting in to Play AppSigning is highly recommended because it increases the security of your signing key. As notedbefore, Google Play will soon require all new apps be uploaded in the AAB format, so werecommend 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 AppSigning, you are fully responsible for your app's signing key. Unlike with Play App Signing, it isnot possible to reset it if you lose the key. Therefore, losing your app's signing key means youalso lose the ability to update your app.

During thebubblewrap 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. Thedefault key store location is the fileandroid.keystore in your project directory and the defaultkey name isandroid. If Bubblewrap doesn't find an existing keystore with that key name at thelocation, it will create one for you and also prompt you for passwords. Take note of the passwordsyou entered as you'll need them during the build process (bubblewrap build) where it will use thekey to sign your app. If you opt in to Play App Signing, then the signing key that Bubblewrapgenerated and used to sign your app becomes the "upload key". Whether you choose to use theBubblewrap 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 withaccess to it.

Digital Asset Links

Digital Asset Links are needed to declare the relationship between your website and your Androidapp. To ensure that your Android app generated by Bubblewrap is verified properly and launches as aTrusted Web Activity (instead of a Chrome Custom Tab), you'll need to add the appropriate key toyourassetlinks.json file. Then upload it to your website at.well-known/assetlinks.json(relative to the root). Yourassetlinks.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 theassetlinks.json file, you'll need the SHA 256 certificate fingerprint associatedwith your app's signing key. The important thing to note is that the fingerprints associated withyoursigning and upload keys will be different. It's important to keepthis distinction in mind, especially if you observe your app launching as a Chrome Custom Tab (withthe browser bar visible). Then, it's likely yourassetlinks.json file does not have thefingerprint that corresponds to the appropriate key.

It's useful to have both your signing and upload certificate's fingerprint in your assetlinks.jsonto more easily debug your app locally. SeeAdding More Keys below for moreinformation on how to have both keys in theassetlinks.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 mostconvenient.

Via Play Console

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

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

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

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

Viakeytool

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

keytool-printcert-jarfile[pathtoAPKorAAB]|grepSHA256

Via Asset Link Tool

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

1. Install theAsset 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 yourdevice by package name. Filter the list by the application ID you chose earlier duringbubblewrap 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 theCopy 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 theGoogle Play Store, the Asset Link Tool will get you the fingerprint for your app's signing key. Ifyou installed the app directly from your local machine, then the fingerprint is for the keyBubblewrap 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 thathttps://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 ofconfiguration so that the.well-known directory is included in the output.GitHub help hasmore information on this topic.Create a file called_config.yml at the root of your site (or add to it if it already exists) andenter:

# 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 thanone key.For example, to add a second key, just use theAsset Link Tool todetermine 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 anextra 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 anAndroid device withadb logcat.If you're developing on Linux/Mac, you can see the relevant logs from a connected devicewith:

>adblogcat-vbrief|grep-eOriginVerifier-edigital_asset_links

For example, if you see the messageStatement failure matching fingerprint., you should use theAsset Link Tool to see your app's signature and make sure it matches that in yourassetlinks.jsonfile.