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