| # 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`). |
