Add display override to TWA manifest (#947)

Author: adamraine

packages/core/src/lib/TwaManifest.ts

@@ -21,7 +21,12 @@ import {fetchUtils} from './FetchUtils';
 import {findSuitableIcon, generatePackageId, validateNotEmpty} from './util';
 import Color = require('color');
 import {ConsoleLog} from './Log';
-import {ShareTarget, WebManifestIcon, WebManifestJson} from './types/WebManifest';
+import {
+  ShareTarget,
+  WebManifestDisplayOverrideValue,
+  WebManifestIcon,
+  WebManifestJson,
+} from './types/WebManifest';
 import {processProtocolHandlers, ProtocolHandler} from './types/ProtocolHandler';
 import {ShortcutInfo} from './ShortcutInfo';
 import {AppsFlyerConfig} from './features/AppsFlyerFeature';
@@ -50,6 +55,20 @@ export function asDisplayMode(input: string): DisplayMode | null {
   return DISPLAY_MODE_VALUES.includes(input) ? input as DisplayMode : null;
 }
 
+// Supported display overrides for TWA
+export type DisplayOverrideValue = WebManifestDisplayOverrideValue | 'fullscreen-sticky';
+export const DisplayOverrideValues: DisplayOverrideValue[] = ['standalone', 'minimal-ui',
+  'fullscreen', 'fullscreen-sticky', 'browser', 'window-controls-overlay', 'tabbed'];
+
+export function resolveDisplayOverride(
+    displayOverride: WebManifestDisplayOverrideValue[]|undefined,
+): DisplayOverrideValue[] {
+  if (!displayOverride) return [];
+
+  return displayOverride.filter(
+      (displayOverrideValue) => DisplayOverrideValues.includes(displayOverrideValue));
+}
+
 // Possible values for screen orientation, as defined in `android-browser-helper`:
 // https://github.com/GoogleChrome/android-browser-helper/blob/alpha/androidbrowserhelper/src/main/java/com/google/androidbrowserhelper/trusted/LauncherActivityMetadata.java#L191-L216
 const ORIENTATION_VALUES = ['default', 'any', 'natural', 'landscape', 'portrait',
@@ -139,6 +158,7 @@ export class TwaManifest {
   name: string;
   launcherName: string;
   display: DisplayMode;
+  displayOverride: DisplayOverrideValue[];
   themeColor: Color;
   themeColorDark: Color;
   navigationColor: Color;
@@ -228,6 +248,7 @@ export class TwaManifest {
     this.protocolHandlers = data.protocolHandlers;
     this.fileHandlers = data.fileHandlers;
     this.launchHandlerClientMode = data.launchHandlerClientMode;
+    this.displayOverride = data.displayOverride || [];
   }
 
   /**
@@ -340,6 +361,7 @@ export class TwaManifest {
       launcherName: webManifest['short_name'] ||
         webManifest['name']?.substring(0, SHORT_NAME_MAX_SIZE) || DEFAULT_APP_NAME,
       display: asDisplayMode(webManifest['display']!) || DEFAULT_DISPLAY_MODE,
+      displayOverride: resolveDisplayOverride(webManifest['display_override']),
       themeColor: webManifest['theme_color'] || DEFAULT_THEME_COLOR,
       themeColorDark: DEFAULT_THEME_COLOR_DARK,
       navigationColor: DEFAULT_NAVIGATION_COLOR,
@@ -540,6 +562,8 @@ export class TwaManifest {
           webManifest['name']?.substring(0, SHORT_NAME_MAX_SIZE)),
       display: this.getNewFieldValue('display', fieldsToIgnore, oldTwaManifest.display,
           asDisplayMode(webManifest['display']!)!),
+      displayOverride: this.getNewFieldValue('displayOverride', fieldsToIgnore,
+          oldTwaManifest.displayOverride, resolveDisplayOverride(webManifest['display_override'])),
       fullScopeUrl: this.getNewFieldValue('fullScopeUrl', fieldsToIgnore,
           oldTwaManifest.fullScopeUrl?.toString(), fullScopeUrl.toString()),
       themeColor: this.getNewFieldValue('themeColor', fieldsToIgnore,
@@ -571,6 +595,7 @@ export interface TwaManifestJson {
   name: string;
   launcherName?: string; // Older Manifests may not have this field.
   display?: string; // Older Manifests may not have this field.
+  displayOverride?: DisplayOverrideValue[];
   themeColor: string;
   themeColorDark?: string;
   navigationColor: string;

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

@@ -35,6 +35,9 @@ export interface WebManifestShortcutJson {
 
 type WebManifestDisplayMode = 'browser' | 'minimal-ui' | 'standalone' | 'fullscreen';
 
+export type WebManifestDisplayOverrideValue = 'window-controls-overlay' | 'tabbed' | 'browser' |
+    'minimal-ui' | 'standalone' | 'fullscreen';
+
 export type OrientationLock = 'any' | 'natural' | 'landscape'| 'portrait' | 'portrait-primary'|
     'portrait-secondary' | 'landscape-primary' | 'landscape-secondary';
 
@@ -64,6 +67,7 @@ export interface WebManifestJson {
   start_url?: string;
   scope?: string;
   display?: WebManifestDisplayMode;
+  display_override?: WebManifestDisplayOverrideValue[];
   theme_color?: string;
   background_color?: string;
   icons?: Array<WebManifestIcon>;

packages/core/src/spec/lib/TwaManifestSpec.ts

@@ -14,7 +14,12 @@
  *  limitations under the License.
  */
 
-import {TwaManifest, TwaManifestJson, asDisplayMode} from '../../lib/TwaManifest';
+import {
+  TwaManifest,
+  TwaManifestJson,
+  asDisplayMode,
+  resolveDisplayOverride,
+} from '../../lib/TwaManifest';
 import {WebManifestJson} from '../../lib/types/WebManifest';
 import Color = require('color');
 import {ShortcutInfo} from '../../lib/ShortcutInfo';
@@ -208,6 +213,7 @@ describe('TwaManifest', () => {
         startUrl: '/',
         iconUrl: 'https://pwa-directory.com/favicons/android-chrome-512x512.png',
         display: 'fullscreen',
+        displayOverride: ['window-controls-overlay'],
         orientation: 'landscape',
         themeColor: '#00ff00',
         themeColorDark: '#000000',
@@ -243,6 +249,7 @@ describe('TwaManifest', () => {
       expect(twaManifest.startUrl).toEqual(twaManifest.startUrl);
       expect(twaManifest.iconUrl).toEqual(twaManifest.iconUrl);
       expect(twaManifest.display).toEqual('fullscreen');
+      expect(twaManifest.displayOverride).toEqual(['window-controls-overlay']);
       expect(twaManifest.orientation).toEqual('landscape');
       expect(twaManifest.themeColor).toEqual(new Color('#00ff00'));
       expect(twaManifest.themeColorDark).toEqual(new Color('#000000'));
@@ -347,6 +354,39 @@ describe('TwaManifest', () => {
       expect(asDisplayMode('')).toBeNull();
     });
   });
+
+  describe('#resolveDisplayOverride', () => {
+    it('Keeps display override values that are supported', () => {
+      expect(resolveDisplayOverride([
+        'browser',
+        'fullscreen',
+        'minimal-ui',
+        'standalone',
+        'window-controls-overlay',
+        'tabbed',
+      ])).toEqual([
+        'browser',
+        'fullscreen',
+        'minimal-ui',
+        'standalone',
+        'window-controls-overlay',
+        'tabbed',
+      ]);
+    });
+
+    it('Ignore unsupported values', () => {
+      expect(resolveDisplayOverride([
+        'browser',
+        // @ts-expect-error Unsupported value for testing
+        'not-supported',
+      ])).toEqual(['browser']);
+      expect(resolveDisplayOverride([
+        // @ts-expect-error Unsupported value for testing
+        'not-supported',
+      ])).toEqual([]);
+    });
+  });
+
   describe('#merge', () => {
     it('Validates that the merge is done correctly in case which' +
         ' there are no fields to ignore', async () => {
@@ -380,6 +420,7 @@ describe('TwaManifest', () => {
         'name': 'name',
         'launcherName': 'name',
         'display': 'standalone',
+        'displayOverride': ['window-controls-overlay'],
         'themeColor': '#FFFFFF',
         'themeColorDark': '#000000',
         'navigationColor': '#000000',
@@ -425,6 +466,7 @@ describe('TwaManifest', () => {
         ...twaManifest.toJson(),
         'launcherName': 'different_name',
         'display': 'fullscreen',
+        'displayOverride': [],
         'protocolHandlers': [
           {
             'protocol': 'web+test-replace',

packages/core/template_project/app/src/main/AndroidManifest.xml

@@ -181,6 +181,12 @@
                     android:resource="@array/additional_trusted_origins" />
             <% } %>
 
+            <% if (displayOverride.length > 0) { %>
+                <meta-data
+                    android:name="android.support.customtabs.trusted.DISPLAY_OVERRIDE"
+                    android:resource="@array/display_override" />
+            <% } %>
+
             <% if (shareTargetIntentFilter) { %>
                 <intent-filter>
                     <% for (const action of shareTargetIntentFilter.actions) { %>

packages/core/template_project/app/src/main/res/values/strings.xml

@@ -23,6 +23,24 @@
     </string-array>
   <% } %>
 
+  <!--
+    The "fullscreen" and "fullscreen-sticky" TWA manifest values correspond to "immersive" and "sticky-immersive"
+    AndroidManifest values.
+  -->
+  <% if (displayOverride.length > 0) { %>
+    <string-array name="display_override">
+    <% for (const displayOverrideValue of displayOverride) { %>
+      <% if (displayOverrideValue === 'fullscreen') { %>
+        <item>immersive</item>
+      <% } else if (displayOverrideValue === 'fullscreen-sticky') { %>
+        <item>sticky-immersive</item>
+      <% } else { %>
+        <item><%= displayOverrideValue %></item>
+      <% } %>
+    <% } %>
+    </string-array>
+  <% } %>
+
   <!--
     This variable below expresses the relationship between the app and the site,
     as documented in the TWA documentation at