App-facing updates

packages/url_launcher/url_launcher/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 6.2.0
+
+* Adds `supportsLaunchMode` for checking whether the current platform supports a
+  given launch mode, to allow clients that will only work with specific modes
+  to avoid fallback to a different mode.
+* Adds `supportsCloseForLaunchMode` to allow checking programatically if a
+  launched URL will be able to be closed. Previously the documented behvaior was
+  that it worked only with the `inAppWebView` launch mode, but this is no longer
+  true on all platforms with the addition of `inAppBrowserView`.
+* Updates the documention for `launchUrl` to clarify that clients should not
+  rely on any specific behavior of the `platformDefault` launch mode. Changes
+  to the handling of `platformDefault`, such as Android's recent change from
+  `inAppBrowserView` to the new `inAppBrowserView`, are not considered breaking.
+
 ## 6.1.14
 
 * Updates documentation to mention support for Android Custom Tabs.

packages/url_launcher/url_launcher/example/lib/main.dart

@@ -99,15 +99,15 @@ class _MyHomePageState extends State<MyHomePage> {
     }
   }
 
-  Future<void> _launchUniversalLinkIos(Uri url) async {
+  Future<void> _launchUniversalLinkIOS(Uri url) async {
     final bool nativeAppLaunchSucceeded = await launchUrl(
       url,
       mode: LaunchMode.externalNonBrowserApplication,
     );
     if (!nativeAppLaunchSucceeded) {
       await launchUrl(
         url,
-        mode: LaunchMode.inAppWebView,
+        mode: LaunchMode.inAppBrowserView,
       );
     }
   }
@@ -198,7 +198,7 @@ class _MyHomePageState extends State<MyHomePage> {
               const Padding(padding: EdgeInsets.all(16.0)),
               ElevatedButton(
                 onPressed: () => setState(() {
-                  _launched = _launchUniversalLinkIos(toLaunch);
+                  _launched = _launchUniversalLinkIOS(toLaunch);
                 }),
                 child: const Text(
                     'Launch a universal link in a native app, fallback to Safari.(Youtube)'),

packages/url_launcher/url_launcher/lib/src/link.dart

@@ -126,7 +126,7 @@ class DefaultLinkDelegate extends StatelessWidget {
       success = await launchUrl(
         url,
         mode: _useWebView
-            ? LaunchMode.inAppWebView
+            ? LaunchMode.inAppBrowserView
             : LaunchMode.externalApplication,
       );
     } on PlatformException {

packages/url_launcher/url_launcher/lib/src/type_conversion.dart

@@ -22,6 +22,8 @@ PreferredLaunchMode convertLaunchMode(LaunchMode mode) {
   switch (mode) {
     case LaunchMode.platformDefault:
       return PreferredLaunchMode.platformDefault;
+    case LaunchMode.inAppBrowserView:
+      return PreferredLaunchMode.inAppBrowserView;
     case LaunchMode.inAppWebView:
       return PreferredLaunchMode.inAppWebView;
     case LaunchMode.externalApplication:

packages/url_launcher/url_launcher/lib/src/types.dart

@@ -14,9 +14,12 @@ enum LaunchMode {
   /// implementation.
   platformDefault,
 
-  /// Loads the URL in an in-app web view (e.g., Android Custom Tabs, Safari View Controller).
+  /// Loads the URL in an in-app web view (e.g., Android WebView).
   inAppWebView,
 
+  /// Loads the URL in an in-app web view (e.g., Android Custom Tabs, SFSafariViewController).
+  inAppBrowserView,
+
   /// Passes the URL to the OS to be handled by another application.
   externalApplication,
 

packages/url_launcher/url_launcher/lib/src/url_launcher_string.dart

@@ -25,7 +25,8 @@ Future<bool> launchUrlString(
   WebViewConfiguration webViewConfiguration = const WebViewConfiguration(),
   String? webOnlyWindowName,
 }) async {
-  if (mode == LaunchMode.inAppWebView &&
+  if ((mode == LaunchMode.inAppWebView ||
+          mode == LaunchMode.inAppBrowserView) &&
       !(urlString.startsWith('https:') || urlString.startsWith('http:'))) {
     throw ArgumentError.value(urlString, 'urlString',
         'To use an in-app web view, you must provide an http(s) URL.');

packages/url_launcher/url_launcher/lib/src/url_launcher_uri.dart

@@ -11,25 +11,13 @@ import 'type_conversion.dart';
 
 /// Passes [url] to the underlying platform for handling.
 ///
-/// [mode] support varies significantly by platform:
-///   - [LaunchMode.platformDefault] is supported on all platforms:
-///     - On iOS and Android, this treats web URLs as
-///       [LaunchMode.inAppWebView], and all other URLs as
-///       [LaunchMode.externalApplication].
-///     - On Windows, macOS, and Linux this behaves like
-///       [LaunchMode.externalApplication].
-///     - On web, this uses `webOnlyWindowName` for web URLs, and behaves like
-///       [LaunchMode.externalApplication] for any other content.
-///   - [LaunchMode.inAppWebView] is currently only supported on iOS and
-///     Android. If a non-web URL is passed with this mode, an [ArgumentError]
-///     will be thrown.
-///   - [LaunchMode.externalApplication] is supported on all platforms.
-///     On iOS, this should be used in cases where sharing the cookies of the
-///     user's browser is important, such as SSO flows, since Safari View
-///     Controller does not share the browser's context.
-///   - [LaunchMode.externalNonBrowserApplication] is supported on iOS 10+.
-///     This setting is used to require universal links to open in a non-browser
-///     application.
+/// [mode] support varies significantly by platform. Clients can use
+/// [supportsLaunchMode] to query for support, but platforms will fall back to
+/// other modes if the requested mode is not supported, so checking is not
+/// required. The default behavior of [LaunchMode.platformDefault] is up to each
+/// platform, and its behavior for a given platform may change over time as new
+/// modes are supported, so clients that want a specific mode should request it
+/// rather than rely on any currently observed default behavior.
 ///
 /// For web, [webOnlyWindowName] specifies a target for the launch. This
 /// supports the standard special link target names. For example:
@@ -45,7 +33,8 @@ Future<bool> launchUrl(
   WebViewConfiguration webViewConfiguration = const WebViewConfiguration(),
   String? webOnlyWindowName,
 }) async {
-  if (mode == LaunchMode.inAppWebView &&
+  if ((mode == LaunchMode.inAppWebView ||
+          mode == LaunchMode.inAppBrowserView) &&
       !(url.scheme == 'https' || url.scheme == 'http')) {
     throw ArgumentError.value(url, 'url',
         'To use an in-app web view, you must provide an http(s) URL.');
@@ -81,8 +70,26 @@ Future<bool> canLaunchUrl(Uri url) async {
 /// Closes the current in-app web view, if one was previously opened by
 /// [launchUrl].
 ///
-/// If [launchUrl] was never called with [LaunchMode.inAppWebView], then this
-/// call will have no effect.
+/// This works only if [supportsCloseForLaunchMode] returns true for the mode
+/// that was used by [launchUrl].
 Future<void> closeInAppWebView() async {
   return UrlLauncherPlatform.instance.closeWebView();
 }
+
+/// Returns true if [mode] is supported by the current platform implementation.
+///
+/// Calling [launchUrl] with an unsupported mode will fall back to a supported
+/// mode, so calling this method is only necessary for cases where the caller
+/// needs to know which mode will be used.
+Future<bool> supportsLaunchMode(PreferredLaunchMode mode) {
+  return UrlLauncherPlatform.instance.supportsMode(mode);
+}
+
+/// Returns true if [closeInAppWebView] is supported for [mode] in the current
+/// platform implementation.
+///
+/// If this returns false, [closeInAppWebView] will not work when launching
+/// URLs with [mode].
+Future<bool> supportsCloseForLaunchMode(PreferredLaunchMode mode) {
+  return UrlLauncherPlatform.instance.supportsMode(mode);
+}

packages/url_launcher/url_launcher/pubspec.yaml

@@ -3,7 +3,7 @@ description: Flutter plugin for launching a URL. Supports
   web, phone, SMS, and email schemes.
 repository: https://github.com/flutter/packages/tree/main/packages/url_launcher/url_launcher
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+url_launcher%22
-version: 6.1.14
+version: 6.2.0
 
 environment:
   sdk: ">=3.0.0 <4.0.0"

packages/url_launcher/url_launcher/test/link_test.dart

@@ -86,7 +86,7 @@ void main() {
       mock
         ..setLaunchExpectations(
           url: 'http://example.com/foobar',
-          launchMode: PreferredLaunchMode.inAppWebView,
+          launchMode: PreferredLaunchMode.inAppBrowserView,
           universalLinksOnly: false,
           enableJavaScript: true,
           enableDomStorage: true,

packages/url_launcher/url_launcher/test/mocks/mock_url_launcher_platform.dart

@@ -107,4 +107,16 @@ class MockUrlLauncher extends Fake
   Future<void> closeWebView() async {
     closeWebViewCalled = true;
   }
+
+  @override
+  Future<bool> supportsMode(PreferredLaunchMode mode) async {
+    launchMode = mode;
+    return response!;
+  }
+
+  @override
+  Future<bool> supportsCloseForMode(PreferredLaunchMode mode) async {
+    launchMode = mode;
+    return response!;
+  }
 }

packages/url_launcher/url_launcher/test/src/url_launcher_uri_test.dart

@@ -248,4 +248,40 @@ void main() {
       expect(await launchUrl(emailLaunchUrl), isTrue);
     });
   });
+
+  group('supportsLaunchMode', () {
+    test('handles returning true', () async {
+      const PreferredLaunchMode mode = PreferredLaunchMode.inAppBrowserView;
+      mock.setResponse(true);
+
+      expect(await supportsLaunchMode(mode), true);
+      expect(mock.launchMode, mode);
+    });
+
+    test('handles returning false', () async {
+      const PreferredLaunchMode mode = PreferredLaunchMode.inAppBrowserView;
+      mock.setResponse(false);
+
+      expect(await supportsLaunchMode(mode), false);
+      expect(mock.launchMode, mode);
+    });
+  });
+
+  group('supportsCloseForLaunchMode', () {
+    test('handles returning true', () async {
+      const PreferredLaunchMode mode = PreferredLaunchMode.inAppBrowserView;
+      mock.setResponse(true);
+
+      expect(await supportsCloseForLaunchMode(mode), true);
+      expect(mock.launchMode, mode);
+    });
+
+    test('handles returning false', () async {
+      const PreferredLaunchMode mode = PreferredLaunchMode.inAppBrowserView;
+      mock.setResponse(false);
+
+      expect(await supportsCloseForLaunchMode(mode), false);
+      expect(mock.launchMode, mode);
+    });
+  });
 }