How to Choose and Configure an Android TWA Package Name

When preparing to package your Progressive Web App (PWA) into an Android application package (APK) or Android App Bundle (AAB) using a Trusted Web Activity (TWA), one of the most critical structural decisions you must make is selecting your Android package name. Also known as the Application ID, the package name acts as a unique global identifier for your application across the entire Android ecosystem, including the Google Play Store and the local device operating system.

What is an Android Package Name?

An Android package name is a unique string that identifies your application. The operating system uses this string to manage application installations, handle permissions, handle background tasks, and route deep links. The Google Play Store uses it as the unique database key for your application listing. Unlike your application's public-facing title, which can be modified at any time, the package name is permanently tied to your application once you upload your build to the Google Play Console.

Naming Conventions and Rules

Google enforces strict technical and structural rules for package names. To ensure your application compiles successfully and passes Google Play automated intake validation, your package name must adhere to the following constraints:

• It must use reverse domain name notation. This format typically starts with the top-level domain of your organisation, followed by the domain name, and optionally followed by specific subdomains or project names (for example, com.example.myapp).
• It must contain at least two individual segments separated by a full stop (period). For example, com.myapp is valid, but myapp is invalid.
• Each individual segment must begin with a letter, not a number or symbol.
• The string must contain only alphanumeric characters (a-z, A-Z, 0-9) and underscores. No hyphens, spaces, or special characters are permitted.
• The package name must be entirely unique. You cannot use a package name that is already in use by another developer on the Google Play Store.

Best Practices for TWA Naming Schemes

When translating a web-based brand to an Android app, your package name should reflect your web domain's structure. This maintains clean architecture and prevents conflicts with other properties you might own. Refer to the following table for examples of how to map web domains to valid Android package names:

The Permanent Nature of Package Names

It is vital to finalise your package name before publishing your application to production or sharing it with beta testers. Once you register a package name on the Google Play Console by uploading an APK or AAB to any release track (including internal test tracks), that package name is locked. To use a different package name, you would have to create a completely new app entry in the Play Console, pay the one-off 25 USD developer registration fee again if registering under a separate developer identity, and re-submit your app for review. Furthermore, any users who installed the previous version would not receive updates, as Android treats different package names as completely separate applications. You would lose all accumulated app reviews, store rankings, and installation history.

Linking the Package Name to Digital Asset Links

For Trusted Web Activities, the package name has a direct operational link to web security. To remove the browser address bar and run your app in a fully immersive native frame, Google requires verification of ownership through Digital Asset Links. This verification requires you to upload an assetlinks.json file to your web server under the .well-known directory. This file contains a configuration object that explicitly references your package name and your app's SHA-256 signing certificate fingerprint. Below is an example of an asset links configuration showing this connection:

[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.mybrand.app",
"sha256_cert_fingerprints": ["A1:B2:C3:D4:E5..."]
}
}]

If the package_name value in your assetlinks.json file does not exactly match the package name defined in your TWA build configuration, the Digital Asset Links verification will fail. The app will launch with the Chrome URL bar visible at the top of the screen, ruining the native experience for your users.

How to Configure the Package Name in Your Project Files

When compiling your TWA using standard build tools or Android Studio, the package name is defined in your build configuration files. In a Gradle-based Android project, you set this inside the app-level build.gradle file under the defaultConfig block using the applicationId property:

android {
compileSdkVersion 33
defaultConfig {
applicationId "com.mybrand.app"
minSdkVersion 21
targetSdkVersion 33
versionCode 1
versionName "1.0.0"
}
}

You must also ensure that the package name is accurately specified in your AndroidManifest.xml file within the root manifest tag. By carefully selecting your package name at the start of your project, maintaining matches across your web asset associations, and preserving it throughout your build pipelines, you will ensure a smooth publishing experience on Google Play.