| # Identifiers in Web Apps | |
| This document clarifies the differences between various identifiers used in the | |
| context of Web Apps (PWAs, WebAPKs, and TWAs) within Chromium and on different | |
| platforms. | |
| ## Core Web App Identifiers (Cross-Platform) | |
| These identifiers are platform-independent and are defined by web standards or | |
| Chrome's core architecture. | |
| ### 1. Web Manifest ID | |
| - **Scope**: Web Application (PWA). | |
| - **Type**: String (defined in `manifest.json` via the `id` member). | |
| - **Source**: Provided by the web developer. | |
| - **Definition**: Uniquely identifies the PWA to the browser. It allows the | |
| browser to track the app even if the start URL or manifest URL changes. | |
| - **Specification**: | |
| [W3C Web Application Manifest - ID member](https://www.w3.org/TR/appmanifest/#id-member). | |
| - **Chromium Representation**: `webapps::ManifestId` (defined in | |
| [manifest_id.h](../common/manifest_id.h)). It is essentially the `start_url` | |
| with the `id` member applied, and fragments stripped. | |
| ### 2. App ID (Chrome-specific) | |
| - **Scope**: Chromium Browser. | |
| - **Type**: 32-character alphanumeric string. | |
| - **Source**: Derived from the Web Manifest ID. | |
| - **Definition**: Used internally by Chrome (especially on Desktop) to identify | |
| the installed app in databases, preferences, and file paths. | |
| - **Chromium Representation**: `webapps::AppId` (defined in | |
| [web_app_id.h](../common/web_app_id.h)). | |
| - **Derivation Algorithm**: | |
| 1. Start with the `ManifestId` string. | |
| 2. Hash using SHA256. | |
| 3. Hash using SHA256 again. | |
| 4. Hex encode into characters 0-f. | |
| 5. Transform to only use alpha characters between a-p (inclusive) for | |
| historical compatibility. | |
| - **Example**: `fedbieoalmbobgfjapopkghdmhgncnaa` | |
| ### 3. Origin and Domain | |
| - **Origin**: The web origin (e.g., `https://example.com`) that the app is | |
| locked to. | |
| - **Domain**: The registrar domain (e.g., `example.com`), typically used for | |
| broader data clearing scopes. | |
| ______________________________________________________________________ | |
| ## Android-Specific Identifiers | |
| On Android, web apps can be integrated with the OS as WebAPKs or TWAs, which | |
| introduces Android OS-level identifiers. | |
| ### Identifiers Breakdown | |
| | Identifier | Scope | Source | WebAPK | Standard TWA | TWA Installer (Auto-Minted) | | |
| | :------------------- | :----------- | :------------------------------------------------------ | :------------------------------------------------------------------ | :------------------------------------------------------------------- | :--------------------------------------------------------------- | | |
| | **Manifest ID** | Web App | Web Developer (in `manifest.json`) | Used to identify the PWA; influences package name. | Optional in manifest; does not influence package name automatically. | Used to identify the PWA; influences package name. | | |
| | **Package Name** | Android OS | Generated by Server/Installer or specified by Developer | `org.chromium.webapk.<hash>` (hash derived from Manifest ID/URL). | Manually specified in Android project (e.g., `com.example.app`). | `com.android.webapp.<hash>` (hash derived from Manifest ID/URL). | | |
| | **Android UID** | Android OS | Assigned by Android at install time | Unique per installation instance (varies by user profile). | Unique per installation instance. | Unique per installation instance. | | |
| | **Android AppId** | Android OS | Assigned by Android at install time | Constant across users for the same app package. | Constant across users for the same app package. | Constant across users for the same app package. | | |
| | **App Name / Label** | User Visible | Web Manifest or Android Project | Derived from `name` or `short_name` in manifest. | Specified in Android project `AndroidManifest.xml`. | Derived from `name` or `short_name` in manifest. | | |
| | **Origin** | Web | Web URL | The web origin (e.g., `https://example.com`) the app is locked to. | The web origin the app is locked to. | The web origin the app is locked to. | | |
| | **Domain** | Web | Derived from Origin | eTLD+1 (e.g., `example.com`) used for broader data clearing scopes. | Used for broader data clearing scopes. | Used for broader data clearing scopes. | | |
| ### 1. Android Package Name | |
| - **Scope**: Android Operating System. | |
| - **Definition**: Uniquely identifies the application on the Android device. | |
| - **WebAPK**: Chrome requests a WebAPK from a minting server. The package name | |
| is `org.chromium.webapk.<hash>`, where the hash is derived from the Manifest | |
| ID. | |
| - **Standard TWA**: The developer builds their own Android app wrapper. They | |
| specify the package name in their `build.gradle` (e.g., `com.example.app`). | |
| - **Auto-minted TWA**: Chrome installs it via Android's `WebAppManager`. The | |
| package name is `com.android.webapp.<hash>`. | |
| ### 2. Android UID (User ID) | |
| - **Scope**: Android Operating System. | |
| - **Type**: Integer. | |
| - **Definition**: `UID = UserId * 100000 + AppId`. | |
| - **Purpose**: Used for process isolation, security sandboxing, and permission | |
| management. | |
| - **Sharing**: Can be shared between packages that request it (via | |
| `sharedUserId` in `AndroidManifest.xml`) and are signed by the same key. | |
| ### 3. Android AppId | |
| - **Scope**: Android Operating System. | |
| - **Type**: Integer. | |
| - **Source**: Part of the UID assigned by the Android system. | |
| - **Purpose**: Identifies the application within the user's space. It is NOT | |
| derived from the Web Manifest. | |
| ## Summary Flow (Android) | |
| `Web Manifest ID` -> (influences) -> `Android Package Name` -> (installed by | |
| Android) -> assigns `Android UID` (containing `Android AppId`). |