Bubblewrap · App Masters

Bubblewrap is a set of tools and libraries designed to help developers to create, build and update projects for Android Applications that launch Progressive Web App (PWA) using Trusted Web Activity (TWA).

Getting Started

You can install the bubblewrap cli or just use the npx.

⚠ Attention! the application must be hosted or tunneled to work AND the application MUST have passed in all PWA insight checks ⚠

Before running any commands be sure to change the package.json file and replace all urls!

Bubblewrap scripts

bubblewrap init: Initialize an android application from a specified web manifest.
- --manifest=APPLICATION_URL/manifest.json*: Use this option to set the web manifest of the application that will be generated.
- --directory=$OUTPUT_PATH: Specify an output folder for the generated android application.
bubblewrap build: Build the project into a apk.
bubblewrap install: Install the application generated on any device connected to the debug.
bubblewrap validate: Validate the application using the Google pageSpeed insight.
- --url=APPLICATION_URL*: Set the web application url to be validated.

Starting the application on localhost

The steps above are the initial configuration you must do to be able to start/generate the apk.

Build and start the web application.
Tunnel the application at port 3000.

⚠ The urls will be only used when generating the project for the first time or when updating

First time: Generate the android project

Be sure to follow the firsts steps to start the web application.
Run npx bubblewrap init --manifest=APPLICATION_URL/manifest.json --directory=./android it will create a folder ./android and start to initialize the android project. (A fill confirm inputs will be prompted)
After initialization go inside the ./android folder created and run the command npx bubblewrap build to build the apk (You will be asked to input the keystore password you've create on the previous step).
Now with the application generate you must get the SHA256 fingerprint from the keystore file generated, you can do this by going to the ./android folder and running the command keytool -list -v -keystore ./KEYSTORE_NAME.keystore -alias KEYSTORE_ALIAS -storepass PASSWORD -keypass PASSWORD after running this you should be able to see the SHA256: XX:XX... then save it, we are gonna use on the next step.

After grabbing the fingerprint you have to configure the TWA assetlinks for this first you have to create a file called assetlinks.json under public/.well-known/ folder on the next application root. (It's content must be)

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "APPLICATION_PACKAGE",
      "sha256_cert_fingerprints": ["KEYSTORE_SHA256_FINGER_PRINT"]
    }
  }
]

After creating the file public/.well-known/assetlinks.json on the web application, you have to restart it.
If you want to run on a device be sure to connect it via adb, use adb devices to list all connected devices and adb connect DEVICE_IP to connect via wifi.
On the web application root run npx bubblewrap install to install the generated application on the connected device.

Android project is already generated

Be sure to follow the firsts steps to start the web application.
If needed update the application by going to the ./android folder and running npx bubblewrap update --manifest=./twa-manifest.json.
Put the generated keystore for the first build on the ./android folder and run the command npx bubblewrap build to build the apk. (You will be asked keystore passwords)
If you want to run on a device be sure to connect it via adb, use adb devices to list all connected devices and adb connect DEVICE_IP to connect via wifi.
On the web application root run npx bubblewrap install to install the generated application on the connected device.

Known Problems

The mobile application is displaying the browser custom bar when opened.
- This problem is related with the assetlinks.json file when configured wrong.