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:
- Go to the Play Console
- Select the app you're interested in
- In the navigation menu on the left, under Release, go to Setup -> App Integrity.
- Copy the SHA256 for the appropriate key: