Merge pull request #928 from GoogleChromeLabs/filehandling

Add file handling support

Author: orbital17

packages/cli/README.md

@@ -393,6 +393,7 @@ Fields:
 |fullScopeUrl|string|false|The navigation scope that the browser considers to be within the app. If the user navigates outside the scope, it reverts to a normal web page inside a browser tab or window. Must be a full URL. Required and used only by Meta Quest devices.|
 |minSdkVersion|number|false|The minimum [Android API Level](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) required for the application to run. Defaults to `23`, if `isMetaQuest` is `true`, and `19` otherwise.|
 |protocolHandlers|[ProtocolHandler](#protocolhandlers)[]|false|List of [Protocol Handlers](#protocolhandlers) supported by the app.|
+|fileHandlers|[FileHandler](#fileHandlers)[]|false|List of [File Hanlders](#fileHandlers) supported by the app.|
 
 ### Features
 
@@ -473,6 +474,16 @@ List of Protocol Handlers registered for the application. These entries may not
 |protocol|string|true|Data scheme to register (e.g. `bitcoin`, `irc`, `web+coffee`).|
 |url|string|true|Formula for converting a custom data scheme back to a http(s) link, must include '%s' and be the same origin as the web manifest file. Example: `https://test.com/?target=%s`|
 
+### FileHandlers
+
+List of File Handlers registered for the application. These entries may not exactly match what was originally in the webmanifest. If a webmanifest entry is incorrect for any reason it will be ignored and a warning will be printed out. See [here](https://developer.chrome.com/docs/capabilities/web-apis/file-handling?hl=en) for more information about file handling and [here](https://wicg.github.io/manifest-incubations/#file_handlers-member) for file_handlers webmanifest spec.
+
+|Name|Type|Required|Description|
+|:--:|:--:|:------:|:---------:|
+|actionUrl|string|true|URL to be navigated to in case of file handler launch matching the according MIME types|
+|mimeTypes|string[]|true|The list of MIME types for the file handler|
+
+
 ## Manually setting up the Environment
 
 ### Get the Java Development Kit (JDK) 17.

packages/core/src/lib/TwaManifest.ts

@@ -29,6 +29,7 @@ import {LocationDelegationConfig} from './features/LocationDelegationFeature';
 import {PlayBillingConfig} from './features/PlayBillingFeature';
 import {FirstRunFlagConfig} from './features/FirstRunFlagFeature';
 import {ArCoreConfig} from './features/ArCoreFeature';
+import {FileHandler, processFileHandlers} from './types/FileHandler';
 
 // The minimum size needed for the app icon.
 const MIN_ICON_SIZE = 512;
@@ -171,6 +172,7 @@ export class TwaManifest {
   additionalTrustedOrigins: string[];
   retainedBundles: number[];
   protocolHandlers?: ProtocolHandler[];
+  fileHandlers?: FileHandler[];
 
   private static log = new ConsoleLog('twa-manifest');
 
@@ -222,6 +224,7 @@ export class TwaManifest {
     this.additionalTrustedOrigins = data.additionalTrustedOrigins || [];
     this.retainedBundles = data.retainedBundles || [];
     this.protocolHandlers = data.protocolHandlers;
+    this.fileHandlers = data.fileHandlers;
   }
 
   /**
@@ -321,6 +324,12 @@ export class TwaManifest {
         fullScopeUrl,
     );
 
+    const fileHandlers = processFileHandlers(
+        webManifest.file_handlers ?? [],
+        fullStartUrl,
+        fullScopeUrl,
+    );
+
     const twaManifest = new TwaManifest({
       packageId: generatePackageId(webManifestUrl.host) || '',
       host: webManifestUrl.host,
@@ -353,6 +362,7 @@ export class TwaManifest {
       orientation: asOrientation(webManifest.orientation) || DEFAULT_ORIENTATION,
       fullScopeUrl: fullScopeUrl.toString(),
       protocolHandlers: processedProtocolHandlers,
+      fileHandlers,
     });
     return twaManifest;
   }
@@ -505,6 +515,18 @@ export class TwaManifest {
     const fullStartUrl: URL = new URL(webManifest['start_url'] || '/', webManifestUrl);
     const fullScopeUrl: URL = new URL(webManifest['scope'] || '.', webManifestUrl);
 
+    let fileHandlers = oldTwaManifestJson.fileHandlers;
+    if (!(fieldsToIgnore.includes('file_handlers'))) {
+      fileHandlers = processFileHandlers(
+          webManifest.file_handlers ?? [],
+          fullStartUrl,
+          fullScopeUrl,
+      );
+      if (fileHandlers.length == 0) {
+        fileHandlers = oldTwaManifestJson.fileHandlers;
+      }
+    }
+
     const twaManifest = new TwaManifest({
       ...oldTwaManifestJson,
       name: this.getNewFieldValue('name', fieldsToIgnore, oldTwaManifest.name,
@@ -527,6 +549,7 @@ export class TwaManifest {
       monochromeIconUrl: monochromeIconUrl || oldTwaManifestJson.monochromeIconUrl,
       shortcuts: shortcuts,
       protocolHandlers: protocolHandlers,
+      fileHandlers,
     });
     return twaManifest;
   }
@@ -583,6 +606,7 @@ export interface TwaManifestJson {
   additionalTrustedOrigins?: string[];
   retainedBundles?: number[];
   protocolHandlers?: ProtocolHandler[];
+  fileHandlers?: FileHandler[];
 }
 
 export interface SigningKeyInfo {

packages/core/src/lib/features/EmptyFeature.ts

@@ -21,9 +21,11 @@ export class EmptyFeature implements Feature {
   buildGradle: {
     repositories: string[];
     dependencies: string[];
+    configs: string[];
   } = {
     repositories: new Array<string>(),
     dependencies: new Array<string>(),
+    configs: new Array<string>(),
   };
 
   androidManifest: {

packages/core/src/lib/features/Feature.ts

@@ -41,6 +41,10 @@ export interface Feature {
      *    Example `androidx.appcompat:appcompat:1.2.0`.
      */
     dependencies: string[];
+    /**
+     * Entries to be added the `android.defaultConfig` section.
+     */
+    configs: string[];
   };
 
   /**

packages/core/src/lib/features/FeatureManager.ts

@@ -23,6 +23,7 @@ import {FirstRunFlagFeature} from './FirstRunFlagFeature';
 import {Log, ConsoleLog} from '../Log';
 import {ArCoreFeature} from './ArCoreFeature';
 import {ProtocolHandlersFeature} from './ProtocolHandlersFeature';
+import {FileHandlingFeature} from './FileHandlingFeature';
 
 const ANDROID_BROWSER_HELPER_VERSIONS = {
   stable: 'com.google.androidbrowserhelper:androidbrowserhelper:2.6.0',
@@ -37,6 +38,7 @@ export class FeatureManager {
   buildGradle = {
     repositories: new Set<string>(),
     dependencies: new Set<string>(),
+    configs: new Set<string>(),
   };
   androidManifest = {
     permissions: new Set<string>(),
@@ -108,6 +110,10 @@ export class FeatureManager {
     if (twaManifest.protocolHandlers) {
       this.addFeature(new ProtocolHandlersFeature(twaManifest.protocolHandlers));
     }
+
+    if (twaManifest.fileHandlers) {
+      this.addFeature(new FileHandlingFeature(twaManifest.fileHandlers));
+    }
   }
 
   private addFeature(feature: Feature): void {
@@ -120,6 +126,10 @@ export class FeatureManager {
       this.buildGradle.dependencies.add(dep);
     });
 
+    feature.buildGradle.configs.forEach((dep) => {
+      this.buildGradle.configs.add(dep);
+    });
+
     // Adds properties to application.
     feature.applicationClass.imports.forEach((imp) => {
       this.applicationClass.imports.add(imp);

packages/core/src/lib/features/FileHandlingFeature.ts

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2025 Google Inc. All Rights Reserved.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+import {EmptyFeature} from './EmptyFeature';
+import {FileHandler} from '../types/FileHandler';
+
+const activityAliasTemplate = (handler: FileHandler, index: number): string => `
+    <activity-alias
+        android:name="FileHandlingActivity${index}"
+        android:targetActivity="LauncherActivity"
+        android:exported="true">
+        <meta-data android:name="android.support.customtabs.trusted.FILE_HANDLING_ACTION_URL"
+            android:value="@string/fileHandlingActionUrl${index}" /> 
+        <intent-filter>
+            <action android:name="android.intent.action.VIEW"/>
+            <category android:name="android.intent.category.DEFAULT" />
+            <category android:name="android.intent.category.BROWSABLE"/>
+            <data android:scheme="content" />
+${ handler.mimeTypes.map((mimeType: string) => `
+            <data android:mimeType="${mimeType}" />`,
+  ).join('') }
+        </intent-filter>
+    </activity-alias>
+`;
+
+export class FileHandlingFeature extends EmptyFeature {
+  constructor(fileHandlers: FileHandler[]) {
+    super('fileHandling');
+    if (fileHandlers.length === 0) return;
+    for (let i = 0; i < fileHandlers.length; i++) {
+      this.androidManifest.components.push(activityAliasTemplate(fileHandlers[i], i));
+      this.buildGradle.configs.push(
+          `resValue "string", "fileHandlingActionUrl${i}", "${fileHandlers[i].actionUrl}"`);
+    }
+  }
+}

packages/core/src/lib/types/FileHandler.ts

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2025 Google Inc. All Rights Reserved.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+export interface FileHandlerJson {
+  action?: string;
+  accept?: {
+    [mimeType: string]: Array<string>;
+  };
+}
+
+export interface FileHandler {
+  actionUrl: string;
+  mimeTypes: Array<string>;
+}
+
+function normalizeUrl(url: string, startUrl: URL, scopeUrl: URL): string | undefined {
+  try {
+    const absoluteUrl = new URL(url, startUrl);
+
+    if (absoluteUrl.protocol !== 'https:') {
+      console.warn('Ignoring url with illegal scheme:', absoluteUrl.toString());
+      return;
+    }
+
+    if (absoluteUrl.origin != scopeUrl.origin) {
+      console.warn('Ignoring url with invalid origin:', absoluteUrl.toString());
+      return;
+    }
+
+    if (!absoluteUrl.pathname.startsWith(scopeUrl.pathname)) {
+      console.warn('Ignoring url not within manifest scope: ', absoluteUrl.toString());
+      return;
+    }
+
+    return absoluteUrl.toString();
+  } catch (error) {
+    console.warn('Ignoring invalid url:', url);
+  }
+}
+
+export function processFileHandlers(
+    fileHandlers: FileHandlerJson[],
+    startUrl: URL,
+    scopeUrl: URL,
+): FileHandler[] {
+  const processedFileHandlers: FileHandler[] = [];
+
+  for (const handler of fileHandlers) {
+    if (!handler.action || !handler.accept) continue;
+
+    const actionUrl = normalizeUrl(handler.action, startUrl, scopeUrl);
+    if (!actionUrl) continue;
+
+    const mimeTypes = Object.keys(handler.accept);
+    if (mimeTypes.length == 0) continue;
+
+    const processedHandler: FileHandler = {
+      actionUrl,
+      mimeTypes,
+    };
+
+    processedFileHandlers.push(processedHandler);
+  }
+
+  return processedFileHandlers;
+}

packages/core/src/lib/types/WebManifest.ts

@@ -15,6 +15,7 @@
  *  limitations under the License.
  */
 
+import {FileHandlerJson} from './FileHandler';
 import {ProtocolHandler} from './ProtocolHandler';
 
 export interface WebManifestIcon {
@@ -70,4 +71,5 @@ export interface WebManifestJson {
   share_target?: ShareTarget;
   orientation?: OrientationLock;
   protocol_handlers?: Array<ProtocolHandler>;
+  file_handlers?: Array<FileHandlerJson>;
 }