Bubblewrap CLI

!Node CI Status

Bubblewrap is a Command Line Interface (CLI) that helps developers to create
a Project for an Android application that launches an existing Progressive Web App (PWA) using a
Trusted Web Activity (TWA).

Requirements

- Node.js 14.15.0 or above

Setting up the Environment

When running Bubblewrap for the first time, it will offer to automatically download and install
external dependencies. This is the recommended setup, but it's possible to
manually setup the environment.

Container

As an alternative to running the cli on your machine with Node.js directly you can use this
container image which got the cli and all dependencies pre-installed. To use the cli run
docker run --rm -ti ghcr.io/googlechromelabs/bubblewrap:latest [cmd] as you would normally
use bubblewrap [cmd].

Quickstart Guide

$3

``bash npm i -g @bubblewrap/cli`

:warning: Warning: Don't use sudo npm i -g @bubblewrap/cli to install Bubblewrap. Using npm commands with sudocan create different kinds of problems and should be avoided (see here and here).

`$3`


Generate an Android project from an existing Web Manifest:

`bash bubblewrap init --manifest https://my-twa.com/manifest.json`

When initalizing a project, Bubblewrap will download the Web Manifest and ask you to confirm the values that should be used when building the Android project.

It will also ask you for the details needed to generate a signing key, used to sign the app before uploading to the Play Store.

> :grey_exclamation: Even though we recommend Bubblewrap for building and generating a signed APK, the output from theinitcommand is a regular Android project that can be opened and built using Android Studio. Please, refer to the documentation to build and sign applications using Android Studio.

`$3`

`bash bubblewrap build`

When building the project for the first time, the Android Build Tools will need to be installed. The tool will invoke the installation process for the build tools. Make sure to read and accept the license agreement before proceeding. This process will install the other required files inside thedirectory/decompressed root directory of the android CLI package.

As a result of the build step, the tool will generate a signed APK (app-release-signed.apk) that can be used for testing the app and a signed AppBundle (./app-release-bundle.aab) that can be uploaded to the Play Store. You will also need to deploy a Digital Asset Links file to validate your domain. The TWA Quick Start Guide explains how to extract the information needed to generate it.

`Commands`

!Overview of bubblewrap commands

The diagram above shows which commands (in the black boxes) take as input or produce as output various files (in white ovals). An arrow leading to a file means "creates or modifies" and an arrow leading to a command means "is used as input".

init

Usage:

Initializes an Android project for Trusted Web Activity from a Web Manifest. The init script will parse the Web manifest and generate default values for the Android project, where possible. It will prompt the user to confirm or input values where one could not be generated.

`bubblewrap init --manifest="" [--directory=""] [--chromeosonly] [--metaquest]`

Options: ---directory: path where to generate the project. Defaults to the current directory. ---chromeosonly: this flag specifies that the build will be used for Chrome OS only and prevents non-Chrome OS devices from installing the app. ---metaquest: this flag specifies that the build will be compatible with Meta Quest devices. ---alphaDependencies: enables features that depend on upcoming version of the Android library for Trusted Web Activity or that are still unstable.

build

Builds the project into a final APK that can be uploaded to the Play Store.

The command will ask the user for they key store passwords. Alternatively, users can set the passwords as enviromental variables, which allows runningbuildas part of a continuous integration. SetBUBBLEWRAP_KEYSTORE_PASSWORD for the key store password and BUBBLEWRAP_KEY_PASSWORD as the key password.

Usage:

`bubblewrap build [--skipPwaValidation] [--skipSigning] [--manifest=""] [--signingKeyPath=""] [--signingKeyAlias=""]`

Options: ---skipPwaValidation: skips validating the wrapped PWA against the Quality Criteria. ---skipSigning: skips signing the built APK and App Bundle. Other signing-related flags are ignored when this is used. ---signingKeyPath: path to keystore to use for signing the built APK and App Bundle. Overrides signingKey.path specified in twa-manifest.json. ---signingKeyAlias: key name. Overrides signingKey.alias specified in twa-manifest.json. ---manifest: directory where the client should look for twa-manifest.json.

update

Regenerates the Android project files from a twa-manifest.json file.

:warning: Warning: Bubblewrap doesn't expect the generated Android project to be updated using external editors. Any files added manually to the Android project will be deleted or overwritten whenupdate is executed. Changes to twa-manifest.json are preserved.

Usage:

`bubblewrap update [--appVersionName=""] [--skipVersionUpgrade] [--manifest=""]`

Options: ---appVersionName: version name to be used on on the upgrade. Ignored if --skipVersionUpgradeis used. ---skipVersionUpgrade: skips upgrading appVersion and appVersionCode. ---manifest: directory where the client should look for twa-manifest.json.

validate

Validates a PWA agains the Quality Criteria for being using in a Trusted Web Activity.

Usage:

`bubblewrap validate --url=[pwa-url]`

install

Install the application generated in the output command to a device connected for debugging.

Usage:

`bubblewrap install [--apkFile="/path-to-apk/apkfile.apk"]`

Options: ---apkFile: path to the APK file to be installed. Defaults to ./app-release-signed.apk. ---verbose: prints the adb command being executed.

help

Displays a list of commands and options.

Usage:

`bubblewrap help`

doctor

Validates that the jdk and the androidSdk are located at the path specified in your config and that they are at the correct version.

Usage:

`bubblewrap doctor`

updateConfig

Sets the paths of the jdk or the androidSdk to the given paths.

Usage:

`bubblewrap updateConfig --jdkPath="/path-to-jdk" --androidSdkPath="/path-to-androidSdk"`

Options: ---jdkPath: sets the jdk's path to the path given. ---androidSdkPath: sets the androidSdk's path to the path given.

merge

Merges the user's web manifest into their twaManifest.json.

Usage:

`bubblewrap merge --ignore [fields-list]`

Options: ---appVersionName: version name to be used on on the upgrade. Ignored if --skipVersionUpgradeis used. ---skipVersionUpgrade: skips upgrading appVersion and appVersionCode. ---ignore: Ignores all of the fields on the list. Accepts all of the possible fields in the Web Manifest.

fingerprint

Manages the list of fingerprints used to generate the Digital Asset Links file for the web application.

Usage:

`bash bubblewrap fingerprint [subcommand]`

Global flags: ---manifest=: path to the Trusted Web Activity configuration.',

`$3`

#### addAdds a fingerprint to the project configuration.

Usage:

`bubblewrap fingerprint add [SHA-256 fingerprint]`

Additional flags: ---name=: optionally set a name to help identify the fingerprint. The name is printed along with the fingerprint when using thelist subcommand.

#### removeRemoves a fingerprint from the project configuration.

Usage:`bubblewrap fingerprint remove [SHA-256 fingerprint]`

#### listLists the fingerprints in the project configuration.

Usage:`bubblewrap fingerprint list`

#### generateAssetLinksGenerates an AssetLinks file from the project configuration

Usage:`bubblewrap fingerprint generateAssetLinks`

Flags: ---output=: path from where to load the project configuration.

play

Manages the artifacts for your Google Play Project.

Usage:

`bash bubblewrap play [subcommand]`

Note: These feature requires a service account file to work correctly. Please see this documentation for setting up a service account.

Global flags (can be applied to all of the features commands): ---serviceAccountFile: sets the service account json file location in the twa-manifest. ---manifest: specifies the manifest file to use if not in the current directory.

`$3`

#### publish

Publishes provided bundle to the Play Store.

Usage:

`bash bubblewrap play publish --serviceAccountFile="/path/to/service/account.json" --track="beta" --appBundleLocation="/home/appBundle.aab"`

Options: ---track: publishes the prebuilt file to the Google Play Store specificed track (defaults to internal track). ---appBundleLocation: specifies the location of the appbundle to upload to Google Play (defaults to current directory).

#### retain

:warning: This is an experimental feature.

Usage:

`bash bubblewrap play retain --add=86`

Options: ---add: specifies the bundles to retain for release (this would be Android only bundles if releasing a Chrome OS only release). ---remove: removes the specified bundle if no longer relevant. ---list: shows a list of existing retained bundles in the twa-manifest.json, not what is listed as retained from play.

#### versionCheck

Usage:

`bash bubblewrap play versionCheck --serviceAccountFile="/path/to/service/account.json" --targetDirectory="/home/my/app/dir"`

Options: ---targetDirectory: the directory that versionCheck should run in (defaults to the current directory). This should be your bubblewrap project directory.

twa-manifest.json `reference`

The twa-manifest.json file is generated as by the initcomand and contains the configuration of Android application.

Developers who want to change their application configuration after running initcan do so by editing this file then running theupdate command.

Fields:

`$3`

Developers can enable additional features in their Android application. Some features may include more dependencies into the application and increase the binary size.

#### AppsFlyerConfig Enables the AppsFlyer SDK in the Android application. Includes additional libraries and is not compatible with Chrome OS.

#### LocationDelegationConfig

Delegates the location permission dialog to the Android system, instead of showing the browser dialog. Recommended when the application requests the location permission, but not enabled by default as it includes additional dependencies in the application.

|Name|Type|Required|Description| |:--:|:--:|:------:|:---------:| |enabled|boolean|true|Set totrue to enable the feature.|

#### PlayBillingConfig

Enables the Play Billing integration in the application and allows the web application to use the Digital Goods API to receive payments. Includes additional dependencies in the Android app.

|Name|Type|Required|Description| |:--:|:--:|:------:|:---------:| |enabled|boolean|true|Set totrue to enable the feature.|

#### FirstRunFlagConfig

Adds an extra query parameter when launching the application, indicating if the application is run for the first time.

`$3`

|Name|Type|Required|Description| |:--:|:--:|:------:|:---------:| |enabled|boolean|false|When set totrue enables the application to use an alpha version of android-browser-helper.|

`$3`

Information on filesystem location and alias used to sign the Android application.

`$3`

Information on the signature fingerprints for the application. Use to generate the assetlinks.json file and managed by the fingerprint command.

`$3`

List of Protocol Handlers registered for the application. These entries may not exactly match what was originally in the webmanifest, because they have been normalized and validated using these rules. If a webmanifest entry is incorrect for any reason (invalid protocol, malformed target url, missing '%s' token) they will be ignored and a warning will be printed out. See here for more information about the Protocol Handler spec. The full list of supported protocols is here.

`$3`

List of File Handlers registered for the application. These entries may not exactly match what was originally in the webmanifest. If a webmanifest entry is incorrect for any reason it will be ignored and a warning will be printed out. See here for more information about file handling and here for file_handlers webmanifest spec.

`$3`


A string, which specifies the context in which the app should be loaded when launched. Possible values are: "auto", "focus-existing", "navigate-existing", "navigate-new".
See launch_handler for more information.

Manually setting up the Environment
$3

The Android Command line tools requires the correct version of the JDK to run. To prevent version
conflicts with a JDK version that is already installed, Bubblewrap uses a JDK that can unzipped in
a separate folder.
Download a version of JDK 17 that is compatible with your OS from
Adoptium
and extract it in its own folder.
:warning: Warning: Using a version lower than 17 will make it impossible to compile the project and higher
versions are incompatible with the Android command line tools.
$3

Download a version of Android command line tools that is compatible with your OS from
https://developer.android.com/studio#command-line-tools-only.
Create a folder and extract the downloaded file into it. This will further install the androidSdk and android SDK manager without needing to install the whole Android IDE.
$3

When running

bubblewrap

 for the first time, it will ask where it can find the JDK and Android command
line tools. So, take note of the location where both were decompressed.

To ensure if you are taking note of the correct location, check if each directory contains the following files: - On Windows and Linux, the correct OpenJDK path should containbin, include ,lib, etc. On MacOS, the directory should contain theContentssubdirectory. - The AndroidSDK path should containtools which should have bin, cli

`$3`


If the location for the JDK or the Android command line tools have been setup with the wrong path or
if their location has changed after the initial configuration, the location for either of those can
be changed by editing the configuration file at

${USER_HOME}/.bubblewrap/config.json.

#### Sample config.json`{ "jdkPath":"\\user\\home\\bubblewrap-user\\open-jdk", "androidSdkPath":"\\user\\home\\bubblewrap-user\\android-cli" }

`(Note : Make sure you don't havespaces` in the androidSdkPath. Check this link for more details.)

Contributing

See CONTRIBUTING for more.

License

See LICENSE for more.

Disclaimer

This is not a Google product.

Bubblewrap CLI

!Node CI Status

Requirements

- Node.js 14.15.0 or above

Setting up the Environment

Container

Quickstart Guide

$3

``bash npm i -g @bubblewrap/cli`

:warning: Warning: Don't use sudo npm i -g @bubblewrap/cli to install Bubblewrap. Using npm commands with sudocan create different kinds of problems and should be avoided (see here and here).

`$3`


Generate an Android project from an existing Web Manifest:

`bash bubblewrap init --manifest https://my-twa.com/manifest.json`

When initalizing a project, Bubblewrap will download the Web Manifest and ask you to confirm the values that should be used when building the Android project.

It will also ask you for the details needed to generate a signing key, used to sign the app before uploading to the Play Store.

`$3`

`bash bubblewrap build`

`Commands`

!Overview of bubblewrap commands

init

Usage:

`bubblewrap init --manifest="" [--directory=""] [--chromeosonly] [--metaquest]`

build

Builds the project into a final APK that can be uploaded to the Play Store.

Usage:

`bubblewrap build [--skipPwaValidation] [--skipSigning] [--manifest=""] [--signingKeyPath=""] [--signingKeyAlias=""]`

update

Regenerates the Android project files from a twa-manifest.json file.

Usage:

`bubblewrap update [--appVersionName=""] [--skipVersionUpgrade] [--manifest=""]`

validate

Validates a PWA agains the Quality Criteria for being using in a Trusted Web Activity.

Usage:

`bubblewrap validate --url=[pwa-url]`

install

Install the application generated in the output command to a device connected for debugging.

Usage:

`bubblewrap install [--apkFile="/path-to-apk/apkfile.apk"]`

Options: ---apkFile: path to the APK file to be installed. Defaults to ./app-release-signed.apk. ---verbose: prints the adb command being executed.

help

Displays a list of commands and options.

Usage:

`bubblewrap help`

doctor

Validates that the jdk and the androidSdk are located at the path specified in your config and that they are at the correct version.

Usage:

`bubblewrap doctor`

updateConfig

Sets the paths of the jdk or the androidSdk to the given paths.

Usage:

`bubblewrap updateConfig --jdkPath="/path-to-jdk" --androidSdkPath="/path-to-androidSdk"`

Options: ---jdkPath: sets the jdk's path to the path given. ---androidSdkPath: sets the androidSdk's path to the path given.

merge

Merges the user's web manifest into their twaManifest.json.

Usage:

`bubblewrap merge --ignore [fields-list]`

Options: ---appVersionName: version name to be used on on the upgrade. Ignored if --skipVersionUpgradeis used. ---skipVersionUpgrade: skips upgrading appVersion and appVersionCode. ---ignore: Ignores all of the fields on the list. Accepts all of the possible fields in the Web Manifest.

fingerprint

Manages the list of fingerprints used to generate the Digital Asset Links file for the web application.

Usage:

`bash bubblewrap fingerprint [subcommand]`

Global flags: ---manifest=: path to the Trusted Web Activity configuration.',

`$3`

#### addAdds a fingerprint to the project configuration.

Usage:

`bubblewrap fingerprint add [SHA-256 fingerprint]`

Additional flags: ---name=: optionally set a name to help identify the fingerprint. The name is printed along with the fingerprint when using thelist subcommand.

#### removeRemoves a fingerprint from the project configuration.

Usage:`bubblewrap fingerprint remove [SHA-256 fingerprint]`

#### listLists the fingerprints in the project configuration.

Usage:`bubblewrap fingerprint list`

#### generateAssetLinksGenerates an AssetLinks file from the project configuration

Usage:`bubblewrap fingerprint generateAssetLinks`

Flags: ---output=: path from where to load the project configuration.

play

Manages the artifacts for your Google Play Project.

Usage:

`bash bubblewrap play [subcommand]`

Note: These feature requires a service account file to work correctly. Please see this documentation for setting up a service account.

`$3`

#### publish

Publishes provided bundle to the Play Store.

Usage:

`bash bubblewrap play publish --serviceAccountFile="/path/to/service/account.json" --track="beta" --appBundleLocation="/home/appBundle.aab"`

#### retain

:warning: This is an experimental feature.

Usage:

`bash bubblewrap play retain --add=86`

#### versionCheck

Usage:

`bash bubblewrap play versionCheck --serviceAccountFile="/path/to/service/account.json" --targetDirectory="/home/my/app/dir"`

Options: ---targetDirectory: the directory that versionCheck should run in (defaults to the current directory). This should be your bubblewrap project directory.

twa-manifest.json `reference`

The twa-manifest.json file is generated as by the initcomand and contains the configuration of Android application.

Developers who want to change their application configuration after running initcan do so by editing this file then running theupdate command.

Fields:

`$3`

Developers can enable additional features in their Android application. Some features may include more dependencies into the application and increase the binary size.

#### AppsFlyerConfig Enables the AppsFlyer SDK in the Android application. Includes additional libraries and is not compatible with Chrome OS.

#### LocationDelegationConfig

|Name|Type|Required|Description| |:--:|:--:|:------:|:---------:| |enabled|boolean|true|Set totrue to enable the feature.|

#### PlayBillingConfig

Enables the Play Billing integration in the application and allows the web application to use the Digital Goods API to receive payments. Includes additional dependencies in the Android app.

|Name|Type|Required|Description| |:--:|:--:|:------:|:---------:| |enabled|boolean|true|Set totrue to enable the feature.|

#### FirstRunFlagConfig

Adds an extra query parameter when launching the application, indicating if the application is run for the first time.

`$3`

|Name|Type|Required|Description| |:--:|:--:|:------:|:---------:| |enabled|boolean|false|When set totrue enables the application to use an alpha version of android-browser-helper.|

`$3`

Information on filesystem location and alias used to sign the Android application.

`$3`

Information on the signature fingerprints for the application. Use to generate the assetlinks.json file and managed by the fingerprint command.

`$3`


A string, which specifies the context in which the app should be loaded when launched. Possible values are: "auto", "focus-existing", "navigate-existing", "navigate-new".
See launch_handler for more information.

Manually setting up the Environment
$3

The Android Command line tools requires the correct version of the JDK to run. To prevent version
conflicts with a JDK version that is already installed, Bubblewrap uses a JDK that can unzipped in
a separate folder.
Download a version of JDK 17 that is compatible with your OS from
Adoptium
and extract it in its own folder.
:warning: Warning: Using a version lower than 17 will make it impossible to compile the project and higher
versions are incompatible with the Android command line tools.
$3

Download a version of Android command line tools that is compatible with your OS from
https://developer.android.com/studio#command-line-tools-only.
Create a folder and extract the downloaded file into it. This will further install the androidSdk and android SDK manager without needing to install the whole Android IDE.
$3

When running

bubblewrap

 for the first time, it will ask where it can find the JDK and Android command
line tools. So, take note of the location where both were decompressed.

`$3`


If the location for the JDK or the Android command line tools have been setup with the wrong path or
if their location has changed after the initial configuration, the location for either of those can
be changed by editing the configuration file at

${USER_HOME}/.bubblewrap/config.json.

#### Sample config.json`{ "jdkPath":"\\user\\home\\bubblewrap-user\\open-jdk", "androidSdkPath":"\\user\\home\\bubblewrap-user\\android-cli" }

`(Note : Make sure you don't havespaces` in the androidSdkPath. Check this link for more details.)

Contributing

See CONTRIBUTING for more.

License

See LICENSE for more.

Disclaimer

This is not a Google product.

@bubblewrap/cli

Dist Tags

Bubblewrap CLI

Requirements

Setting up the Environment

Container

Quickstart Guide

$3

$3

$3

Commands

init

build

update

validate

install

help

doctor

updateConfig

merge

fingerprint

$3

play

$3

twa-manifest.json reference

$3

$3

$3

$3

$3

$3

$3

Manually setting up the Environment

$3

$3

$3

$3

Contributing

License

Disclaimer

@bubblewrap/cli

Dist Tags

Bubblewrap CLI

Requirements

Setting up the Environment

Container

Quickstart Guide

$3

$3

$3

Commands

init

build

update

validate

install

help

doctor

updateConfig

merge

fingerprint

$3

play

$3

twa-manifest.json reference

$3

$3

$3

$3

$3

$3

$3

Manually setting up the Environment

$3

$3

$3

$3

Contributing

License

Disclaimer

`$3`

`$3`

`Commands`

`$3`

`$3`

twa-manifest.json `reference`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Commands`

`$3`

`$3`

twa-manifest.json `reference`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`