A progressive web application (PWA) is a type of application software delivered through the web, built using common web technologies including HTML, CSS and JavaScript. It is intended to work on any platform that uses a standards-compliant browser. Functionality includes working offline, push notifications, and device hardware access, enabling creating user experiences similar to native applications on desktop and mobile devices.
Now it’s easy to upload a PWA to digital distribution systems like Google Play Store, Apple App Store, Microsoft Store or Samsung Galaxy Store. Users can then download your PWA just like any other app. Google allows you to publish your PWA as a native app on Google Play Store via a trusted web activity (TWA). Trusted Web Activities are a new way to integrate your web-app content such as your PWA with your Android app using a protocol based on custom tabs.
1. Download and install Android Studio
Setting up a Trusted Web Activity (TWA) doesn’t require developers to author Java code, but Android Studio is required. So first, download the Android Studio and install it on your development device.
2. Create a Trusted Web Activity project
This section will guide you on setting up a new project on Android Studio.
- Open Android Studio and click on “Start a new Android Studio project”.
- Android Studio will prompt to choose an Activity type. Since TWAs use an Activity provided by support library, choose “Add No Activity” and click “Next”.
- Next step, the wizard will prompt for configurations for the project. Here’s a short description of each field:
- Name: The name that will be used for your application on the Android Launcher.
- Package Name: An unique identifier for Android Applications on the Play Store and on Android devices.
- Save location: Where Android Studio will create the project in the file system.
- Language: The project doesn’t require writing any Java or Kotlin code. Select Java, as the default.
- Minimum API Level: The Support Library requires at least API Level 16. Select API 16 any version above.
- Leave the remaining checkboxes unchecked, as we will not be using Instant Apps or AndroidX artifacts, and click “Finish”.
3. Get the TWA support library
To setup the TWA library in the project you will need to edit the Application build file. Look for the Gradle Scripts section in the Project Navigator. There are two files called build.gradle, which may be a bit confusing and the descriptions in parenthesis help identifying the correct one. The file we are looking for is the one with Module next to its name. The Trusted Web Activities library uses Java 8 features and the first change enables Java 8. Add a compileOptions section to the bottom of the android section, as below:
android {
...
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
The next step will add the TWA Support Library to the project. Add a new dependency to the dependencies section:
dependencies {
implementation 'com.google.androidbrowserhelper:androidbrowserhelper:1.0.0'
}
Android Studio will show prompt asking to synchronize the project once more. Click on the ‘Sync Now’ link and synchronize it.
4. Add the TWA activity
Setting up the TWA Activity is achieved by editing the Android App Manifest.
- On the Project Navigator, expand the app section, followed by the manifests and double click on AndroidManifest.xml to open the file.
- Since we asked Android Studio not to add any activity to our project when creating it, the manifest is empty and contains only the application tag. Add the TWA activity by inserting an activity tag into the application tag.
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.example.twa.myapplication">
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:supportsRtl="true"
android:theme="@style/AppTheme"
tools:ignore="GoogleAppIndexingWarning">
<activity
android:name="com.google.androidbrowserhelper.trusted.LauncherActivity">
<meta-data
android:name="android.support.customtabs.trusted.DEFAULT_URL"
android:value="https://yourwebsite.com" />
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
<action android:name="android.intent.action.VIEW"/>
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE"/>
<data
android:scheme="https"
android:host="yourwebsite.com"/>
The tags added to the XML are standard Android App Manifest. There are two relevant pieces of information for the context of Trusted Web Activities:
- The meta-data tag tells the TWA Activity which URL it should open. Change the android:value attribute with the URL of the PWA you want to open. In this example, it is https://yourwebsite.com.
- The second intent-filter tag allows the TWA to intercept Android Intents that open https://yourwebsite.com. The android:host attribute inside the data tag must point to the domain being opened by the TWA.
5. Remove the URL bar
Trusted Web Activities require an association between the Android application and the website to be established to remove the URL bar. This association is created via Digital Asset Links and the association must be established in both ways, linking from the app to the website and from the website to the app. It is possible to setup the app to website validation and setup Chrome to skip the website to app validation, for debugging purposes.
a. Establish an association the from app to your website
Open the string resources file app > res > values > strings.xml and add the Digital AssetLinks statement below:
<string name="app_name">My App
<string name="asset_statements">
[{
\"relation\": [\"delegate_permission/common.handle_all_urls\"],
\"target\": {
\"namespace\": \"web\",
\"site\": \"https://yourwebsite.com\"}
}]
Change the contents for the site attribute to match the schema and domain opened by the TWA. Back in the Android App Manifest file, AndroidManifest.xml, link to the statement by adding a new meta-data tag, but this time as a child of the application tag:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.twa.myapplication">
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:supportsRtl="true"
android:theme="@style/AppTheme">
<meta-data
android:name="asset_statements"
android:resource="@string/asset_statements" />
...
b. Debug mode
After establishing a relationship from the Android application to the website. It is helpful to debug this part of the relationship without creating the website to application validation. Here’s how to test this on a development device:
- Open Chrome on the development device, navigate to chrome://flags, search for an item called Enable command line on non-rooted devices and change it to ENABLED and then restart the browser.
- Next, on the Terminal application of your operating system, use the Android Debug Bridge (installed with Android Studio), and run the following command:
adb shell "echo '_ --disable-digital-asset-link-verification-for-url=\"https://yourwebsite.com\"' > /data/local/tmp/chrome-command-line"
Close Chrome and re-launch your application from Android Studio. The application should now be shown in full-screen.
c. Establish an association from your website to the app
There are 2 pieces of information that the developer needs to collect from the app in order to create the association:
- Package Name: The first information is the package name for the app. This is the same package name generated when creating the app. It can also be found inside the Module build.gradle, under Gradle Scripts > build.gradle (Module: app), and is the value of the applicationId attribute.
- SHA-256 Fingerprint: Android applications must be signed in order to be uploaded to the Play Store. The same signature is used to establish the connection between the website and the app through the SHA-256 fingerprint of the upload key. You will need the keytool to extract the SHA-256 fingerprint.
How to generate an upload key and keystore using Android studio
You can generate an upload key using Android Studio as follows:
- In the menu bar, click Build > Build > Generate Signed Bundle/APK.
- In the “Generate Signed Bundle or APK” dialog, select “Android App Bundle or APK” and click “Next”.
- Below the field for Key store path, click “Create new”.
- On the New Key Store window, provide the following information for your keystore and key:
- Key store path: Select the location where your keystore should be created.
- Password: Create and confirm a secure password for your keystore.
- Alias: Enter an identifying name for your key.
- Password: Create and confirm a secure password for your key. This should be different from the password you chose for your keystore.
- Validity (years): Set the length of time in years that your key will be valid. Your key should be valid for at least 25 years, so you can sign app updates with the same key through the lifespan of your app.
- Certificate: Enter some information about yourself for your certificate. This information is not displayed in your app, but is included in your certificate as part of the APK.
- Once you complete the form, click “OK”.
- The next dialog box is about signing your app, click “Cancel” as still we are still building the app.
How to use the keytool on Microsoft Windows
You must have Java installed in your Windows PC. To located the keytool;
- Go to Drive C:
- Open the “Programs Files/Programs Files (x86)” folder.
- Open the “Java” folder.
- The keytool is located under the “bin” folder.
- Copy the location of the Java bin folder. For example: C:Program Files (x86)Javajre1.8.0_60bin
- Go to the Start Menu and search for the Command Prompt, just by typing “cmd”.
- Open the Command Prompt.
- Type “cd” then paste the Java bin folder location and press enter. For example: cd C:Program Files (x86)Javajre1.8.0_60bin
- Now you should be able to use the keytool to extract the SHA-256 fingerprint.
Make sure to take note the path, alias and passwords for the key store, as you will need it for the next step. Extract the SHA-256 fingerprint using the keytool, with the following command:
keytool -list -v -keystore -alias -storepass -keypass
If the above command does not work. Just copy your keystore file to your computer’s admin user folder. For example; C:UsersVictor Mochere. Rename the keystore file to simply ‘.keystore‘ and then type the following command:
keytool -list -v
The value for the SHA-256 fingerprint is printed under the certificate fingerprints section. Here’s an example output:
keytool -list -v -keystore ./mykeystore.ks -alias test -storepass password -keypass password
Alias name: key0
Creation date: 28 Jan 2019
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Test Test, OU=Test, O=Test, L=London, ST=London, C=GB
Issuer: CN=Test Test, OU=Test, O=Test, L=London, ST=London, C=GB
Serial number: ea67d3d
Valid from: Mon Jan 28 14:58:00 GMT 2019 until: Fri Jan 22 14:58:00 GMT 2044
Certificate fingerprints:
SHA1: 38:03:D6:95:91:7C:9C:EE:4A:A0:58:43:A7:43:A5:D2:76:52:EF:9B
SHA256: F5:08:9F:8A:D4:C8:4A:15:6D:0A:B1:3F:61:96:BE:C7:87:8C:DE:05:59:92:B2:A3:2D:05:05:A5:62:A5:2F:34
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 2048-bit RSA key
Version: 3
With both pieces of information at hand, head over to the assetlinks generator, fill-in the fields and hit “Generate Statement”. Copy the generated statement and serve it from your domain, from the URL /.well-known/assetlinks.json. You can then hit “Test Statement” to see if the association has been established correctly.
How to create and upload .json file to the root of your domain
Here is a simple way to create and upload .json file to your website.
- After copying the generated statement.
- Go to the location you want to create the file on your computer.
- Right click on a black space.
- Then go to New > Text Document.
- Paste the statement and close the text document.
- You will be prompted to save the changes.
- Rename that document to “assetlinks.json”.
- Go to your website’s cPanel, click on File Manager > File Manager > public_html > .well-known.
- You can then upload the assetlinks.json file to the .well-known folder.
Note:
If you have opted into Google Play signing your app releases. Then to remove the URL bar, you will have to use the SHA-256 fingerprint generated by Google Play for your assetlinks.json file. Go to Google Play Console > Release management > App signing, then copy the App signing certificate SHA-256 fingerprint and paste it into your assetlinks.json file.
6. Creating an icon
When Android Studio creates a new project, it will come with a default icon. As a developer, you will want to create your own icon and differentiate your application from others on the Android Launcher. Android Studio contains the Image Asset Studio, which provides the tools necessary to create the correct icons, for every resolution and shape your application needs. Inside Android Studio, navigate to File > New > Image Asset, select Launcher Icons (Adaptative and Legacy) and follow the steps from the wizard to create a custom icon for the application.
7. Adding a splash screen
Android Studio contains the Vector Asset Studio, which provides the tools to help developers to transform SVGs into Android Vector Drawables. Inside Android Studio, navigate to File > New > Vector Asset to get started. Android devices can have different screen sizes and pixel densities.
To ensure the splash screen looks good on all devices, you will need to generate the image for each pixel density. Below is a list with the pixel densities, the multiplier applied to the base size (320x320dp), the resulting size in pixels and the location where the image should be added in the Android Studio project.
Density | Multiplier | Size | Project Location |
mdpi (baseline) | 1.0x | 320×320 px | /res/drawable-mdpi/ |
ldpi | 0.75x | 240×240 px | /res/drawable-ldpi/ |
hdpi | 1.5x | 480×480 px | /res/drawable-hdpi/ |
xhdpi | 2.0x | 640×640 px | /res/drawable-xhdpi/ |
xxhdpi | 3.0x | 960×960 px | /res/drawable-xxhdpi/ |
xxxhdpi | 4.0x | 1280×1280 px | /res/drawable-xxxhdpi/ |
8. Updating the application
With the images for the icon and splash screen generated, it’s time to add the necessary configurations to the project. First, add a content-provider to the Android Manifest (AndroidManifest.xml).
...
<provider
android:name="androidx.core.content.FileProvider"
android:authorities="com.example.twa.myapplication.fileprovider"
android:grantUriPermissions="true"
android:exported="false">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/filepaths" />
Make sure to change the android:authorities attribute when creating the provider, as two applications cannot have the same authority on a device. Then, add res/xml/filepaths.xml resource, and specify the path to the twa splash screen:
<files-path path="twa_splash/" name="twa_splash" />
Finally, add meta-tags to the Android Manifest to customize the LauncherActivity:
<activity android:name="com.google.androidbrowserhelper.trusted.LauncherActivity">
...
<meta-data android:name="android.support.customtabs.trusted.SPLASH_IMAGE_DRAWABLE"
android:resource="@drawable/splash"/>
<meta-data android:name="android.support.customtabs.trusted.SPLASH_SCREEN_BACKGROUND_COLOR"
android:resource="@color/colorPrimary"/>
<meta-data android:name="android.support.customtabs.trusted.SPLASH_SCREEN_FADE_OUT_DURATION"
android:value="300"/>
<meta-data android:name="android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY"
android:value="com.example.twa.myapplication.fileprovider"/>
...
Ensure that the value of the android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY tag matches the value defined of the android:authorities attribute inside the provider tag.
9. Making the LauncherActivity transparent
Additionally, make sure the LauncherActivity is transparent to avoid a white screen showing before the splash. Add a new theme to res/styles.xml:
<style name="Theme.LauncherActivity" parent="Theme.AppCompat.NoActionBar">
<item name="android:windowAnimationStyle">@null</item>
<item name="android:windowIsTranslucent">true</item>
<item name="android:windowNoTitle">true</item>
<item name="android:windowBackground">@android:color/transparent</item>
<item name="android:backgroundDimEnabled">false</item>
</style>
Then, add a reference to the new style in the Android Manifest:
...
<activity android:name="com.google.androidbrowserhelper.trusted.LauncherActivity"
android:theme="@style/Theme.LauncherActivity">
...
10. Building an app bundle
Building an app bundle instead of APK for upload to Google Play Store has the following benefits.
- Smaller download size.
- On-demand app features.
- Asset-only modules.
To build your app ready for signing; in the menu bar, click Build > Build Bundle(s) / APK(s) > Build Bundle(s).
11. Generating a signed app bundle
Here is how to generate a signed app bundle.
- In the menu bar, click Build > Generate Signed Bundle/APK.
- In the Generate Signed Bundle or APK dialog, select Android App Bundle or APK and click “Next”.
- Select a module from the drop down.
- Specify the path to your keystore, the alias for your key, and enter the passwords for both.
- If you’re signing an app bundle with an existing app signing key, and you’d like to later opt your app into app signing by Google Play, check the box next to Export encrypted key and specify a path to save your signing key as an encrypted *.pepk file. You can then use your encrypted app signing key to opt in an existing app into app signing by Google Play.
- Click “Next”.
- In the next window, select a destination folder for your signed app bundle, select the build type, choose the product flavor(s) if applicable. If your project uses product flavors, you can select multiple product flavors while holding down the Control key on Windows/Linux, or the Command key on Mac OSX. Android Studio will generate a separate APK or app bundle for each product flavor you select.
- Select which Signature Versions you want your app to support.
- Click “Finish”.
12. Uploading your app bundle to Google Play Store
After you build and sign the release version of your app, the next step is to upload it to Google Play Store. And remember that Google Play supports compressed app downloads of only 150 MB or less.
- Go to Google Play Console.
- Pay the mandatory $25 for your developer account.
- Fill the details required.
- Click on All Applications > Create Application.
- Select the language of your app and key in the name/title of your app.
- Enroll into app signing by Google Play, which is the recommended way to upload and sign your app. If you build and upload an Android App Bundle, you must enroll in app signing by Google Play. You can do this under App signing in the Play Console.
- You must fill out all the required information for the store listing, content rating, app content and, pricing and distribution. You should see four green checkmarks on the sidebar when this process is complete.
- Navigate to App releases > Production > Create release. Then upload your Android App Bundle and review. When ready to submit the app for review by Google, hit “Roll-out Production” and the “Confirm roll-out”.
- Your app will be in pending publication status, just wait a few hours for it to be approved.