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:
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.
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
Another way to get the correct Digital Asset Links file for your app, is to use the
Asset Link Tool
:
- Install the
Asset Link Tool
from the Play Store.
- On the same device, download your app from the Google Play Store or install it locally.
- 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.
- 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.