From c3955d221178056351f05f33d042b3b96b08b9a3 Mon Sep 17 00:00:00 2001 From: stuartmorgan Date: Thu, 16 Jun 2022 23:07:36 -0400 Subject: [PATCH] [url_launcher] Add a new launchUrl to platform interface (#5966) This creates a new platform interface method for launching that closely parallels the new public-facing API, so that implementations can switch to implementing a more platform-neutral implementation. This will pave the way for things like cleanly implementing `externalNonBrowserApplication` support on non-iOS platforms. A follow-up will switch the app-facing package to call this new methods instead of the legacy method. Implementation packages can adopt the new method as is useful for them; eventually we can do a cleanup pass if we want to fully deprecate the old method. --- .../CHANGELOG.md | 4 + .../lib/src/types.dart | 69 ++++++++++ .../lib/src/url_launcher_platform.dart | 94 ++++++++++++++ .../lib/url_launcher_platform_interface.dart | 68 +--------- .../pubspec.yaml | 2 +- .../test/url_launcher_platform_test.dart | 121 ++++++++++++++++++ 6 files changed, 291 insertions(+), 67 deletions(-) create mode 100644 packages/url_launcher/url_launcher_platform_interface/lib/src/types.dart create mode 100644 packages/url_launcher/url_launcher_platform_interface/lib/src/url_launcher_platform.dart create mode 100644 packages/url_launcher/url_launcher_platform_interface/test/url_launcher_platform_test.dart diff --git a/packages/url_launcher/url_launcher_platform_interface/CHANGELOG.md b/packages/url_launcher/url_launcher_platform_interface/CHANGELOG.md index 1a9c575c27cb..78818eff7bbf 100644 --- a/packages/url_launcher/url_launcher_platform_interface/CHANGELOG.md +++ b/packages/url_launcher/url_launcher_platform_interface/CHANGELOG.md @@ -1,3 +1,7 @@ +## 2.1.0 + +* Adds a new `launchUrl` method corresponding to the new app-facing interface. + ## 2.0.5 * Updates code for new analysis options. diff --git a/packages/url_launcher/url_launcher_platform_interface/lib/src/types.dart b/packages/url_launcher/url_launcher_platform_interface/lib/src/types.dart new file mode 100644 index 000000000000..08d87e03a128 --- /dev/null +++ b/packages/url_launcher/url_launcher_platform_interface/lib/src/types.dart @@ -0,0 +1,69 @@ +// Copyright 2013 The Flutter Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +import 'package:flutter/foundation.dart'; + +/// The desired mode to launch a URL. +/// +/// Support for these modes varies by platform. Platforms that do not support +/// the requested mode may substitute another mode. +enum PreferredLaunchMode { + /// Leaves the decision of how to launch the URL to the platform + /// implementation. + platformDefault, + + /// Loads the URL in an in-app web view (e.g., Safari View Controller). + inAppWebView, + + /// Passes the URL to the OS to be handled by another application. + externalApplication, + + /// Passes the URL to the OS to be handled by another non-browser application. + externalNonBrowserApplication, +} + +/// Additional configuration options for [PreferredLaunchMode.inAppWebView]. +/// +/// Not all options are supported on all platforms. This is a superset of +/// available options exposed across all implementations. +@immutable +class InAppWebViewConfiguration { + /// Creates a new WebViewConfiguration with the given settings. + const InAppWebViewConfiguration({ + this.enableJavaScript = true, + this.enableDomStorage = true, + this.headers = const {}, + }); + + /// Whether or not JavaScript is enabled for the web content. + final bool enableJavaScript; + + /// Whether or not DOM storage is enabled for the web content. + final bool enableDomStorage; + + /// Additional headers to pass in the load request. + final Map headers; +} + +/// Options for [launchUrl]. +@immutable +class LaunchOptions { + /// Creates a new parameter object with the given options. + const LaunchOptions({ + this.mode = PreferredLaunchMode.platformDefault, + this.webViewConfiguration = const InAppWebViewConfiguration(), + this.webOnlyWindowName, + }); + + /// The requested launch mode. + final PreferredLaunchMode mode; + + /// Configuration for the web view in [PreferredLaunchMode.inAppWebView] mode. + final InAppWebViewConfiguration webViewConfiguration; + + /// A web-platform-specific option to set the link target. + /// + /// Default behaviour when unset should be to open the url in a new tab. + final String? webOnlyWindowName; +} diff --git a/packages/url_launcher/url_launcher_platform_interface/lib/src/url_launcher_platform.dart b/packages/url_launcher/url_launcher_platform_interface/lib/src/url_launcher_platform.dart new file mode 100644 index 000000000000..aa499db4ce6f --- /dev/null +++ b/packages/url_launcher/url_launcher_platform_interface/lib/src/url_launcher_platform.dart @@ -0,0 +1,94 @@ +// Copyright 2013 The Flutter Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +import 'dart:async'; + +import 'package:plugin_platform_interface/plugin_platform_interface.dart'; +import 'package:url_launcher_platform_interface/link.dart'; +import 'package:url_launcher_platform_interface/url_launcher_platform_interface.dart'; + +import '../method_channel_url_launcher.dart'; + +/// The interface that implementations of url_launcher must implement. +/// +/// Platform implementations should extend this class rather than implement it as `url_launcher` +/// does not consider newly added methods to be breaking changes. Extending this class +/// (using `extends`) ensures that the subclass will get the default implementation, while +/// platform implementations that `implements` this interface will be broken by newly added +/// [UrlLauncherPlatform] methods. +abstract class UrlLauncherPlatform extends PlatformInterface { + /// Constructs a UrlLauncherPlatform. + UrlLauncherPlatform() : super(token: _token); + + static final Object _token = Object(); + + static UrlLauncherPlatform _instance = MethodChannelUrlLauncher(); + + /// The default instance of [UrlLauncherPlatform] to use. + /// + /// Defaults to [MethodChannelUrlLauncher]. + static UrlLauncherPlatform get instance => _instance; + + /// Platform-specific plugins should set this with their own platform-specific + /// class that extends [UrlLauncherPlatform] when they register themselves. + // TODO(amirh): Extract common platform interface logic. + // https://github.com/flutter/flutter/issues/43368 + static set instance(UrlLauncherPlatform instance) { + PlatformInterface.verify(instance, _token); + _instance = instance; + } + + /// The delegate used by the Link widget to build itself. + LinkDelegate? get linkDelegate; + + /// Returns `true` if this platform is able to launch [url]. + Future canLaunch(String url) { + throw UnimplementedError('canLaunch() has not been implemented.'); + } + + /// Passes [url] to the underlying platform for handling. + /// + /// Returns `true` if the given [url] was successfully launched. + /// + /// For documentation on the other arguments, see the `launch` documentation + /// in `package:url_launcher/url_launcher.dart`. + Future launch( + String url, { + required bool useSafariVC, + required bool useWebView, + required bool enableJavaScript, + required bool enableDomStorage, + required bool universalLinksOnly, + required Map headers, + String? webOnlyWindowName, + }) { + throw UnimplementedError('launch() has not been implemented.'); + } + + /// Passes [url] to the underlying platform for handling. + /// + /// Returns `true` if the given [url] was successfully launched. + Future launchUrl(String url, LaunchOptions options) { + final bool isWebURL = url.startsWith('http:') || url.startsWith('https:'); + final bool useWebView = options.mode == PreferredLaunchMode.inAppWebView || + (isWebURL && options.mode == PreferredLaunchMode.platformDefault); + + return launch( + url, + useSafariVC: useWebView, + useWebView: useWebView, + enableJavaScript: options.webViewConfiguration.enableJavaScript, + enableDomStorage: options.webViewConfiguration.enableDomStorage, + universalLinksOnly: + options.mode == PreferredLaunchMode.externalNonBrowserApplication, + headers: options.webViewConfiguration.headers, + webOnlyWindowName: options.webOnlyWindowName, + ); + } + + /// Closes the WebView, if one was opened earlier by [launch]. + Future closeWebView() { + throw UnimplementedError('closeWebView() has not been implemented.'); + } +} diff --git a/packages/url_launcher/url_launcher_platform_interface/lib/url_launcher_platform_interface.dart b/packages/url_launcher/url_launcher_platform_interface/lib/url_launcher_platform_interface.dart index 18d64eff8dcb..3312c2f5cd28 100644 --- a/packages/url_launcher/url_launcher_platform_interface/lib/url_launcher_platform_interface.dart +++ b/packages/url_launcher/url_launcher_platform_interface/lib/url_launcher_platform_interface.dart @@ -2,69 +2,5 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. -import 'dart:async'; - -import 'package:plugin_platform_interface/plugin_platform_interface.dart'; -import 'package:url_launcher_platform_interface/link.dart'; - -import 'method_channel_url_launcher.dart'; - -/// The interface that implementations of url_launcher must implement. -/// -/// Platform implementations should extend this class rather than implement it as `url_launcher` -/// does not consider newly added methods to be breaking changes. Extending this class -/// (using `extends`) ensures that the subclass will get the default implementation, while -/// platform implementations that `implements` this interface will be broken by newly added -/// [UrlLauncherPlatform] methods. -abstract class UrlLauncherPlatform extends PlatformInterface { - /// Constructs a UrlLauncherPlatform. - UrlLauncherPlatform() : super(token: _token); - - static final Object _token = Object(); - - static UrlLauncherPlatform _instance = MethodChannelUrlLauncher(); - - /// The default instance of [UrlLauncherPlatform] to use. - /// - /// Defaults to [MethodChannelUrlLauncher]. - static UrlLauncherPlatform get instance => _instance; - - /// Platform-specific plugins should set this with their own platform-specific - /// class that extends [UrlLauncherPlatform] when they register themselves. - // TODO(amirh): Extract common platform interface logic. - // https://github.com/flutter/flutter/issues/43368 - static set instance(UrlLauncherPlatform instance) { - PlatformInterface.verify(instance, _token); - _instance = instance; - } - - /// The delegate used by the Link widget to build itself. - LinkDelegate? get linkDelegate; - - /// Returns `true` if this platform is able to launch [url]. - Future canLaunch(String url) { - throw UnimplementedError('canLaunch() has not been implemented.'); - } - - /// Returns `true` if the given [url] was successfully launched. - /// - /// For documentation on the other arguments, see the `launch` documentation - /// in `package:url_launcher/url_launcher.dart`. - Future launch( - String url, { - required bool useSafariVC, - required bool useWebView, - required bool enableJavaScript, - required bool enableDomStorage, - required bool universalLinksOnly, - required Map headers, - String? webOnlyWindowName, - }) { - throw UnimplementedError('launch() has not been implemented.'); - } - - /// Closes the WebView, if one was opened earlier by [launch]. - Future closeWebView() { - throw UnimplementedError('closeWebView() has not been implemented.'); - } -} +export 'src/types.dart'; +export 'src/url_launcher_platform.dart'; diff --git a/packages/url_launcher/url_launcher_platform_interface/pubspec.yaml b/packages/url_launcher/url_launcher_platform_interface/pubspec.yaml index 140a1aee9938..76461ff7b979 100644 --- a/packages/url_launcher/url_launcher_platform_interface/pubspec.yaml +++ b/packages/url_launcher/url_launcher_platform_interface/pubspec.yaml @@ -4,7 +4,7 @@ repository: https://github.com/flutter/plugins/tree/main/packages/url_launcher/u issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+url_launcher%22 # NOTE: We strongly prefer non-breaking changes, even at the expense of a # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes -version: 2.0.5 +version: 2.1.0 environment: sdk: ">=2.12.0 <3.0.0" diff --git a/packages/url_launcher/url_launcher_platform_interface/test/url_launcher_platform_test.dart b/packages/url_launcher/url_launcher_platform_interface/test/url_launcher_platform_test.dart new file mode 100644 index 000000000000..f764f679f96d --- /dev/null +++ b/packages/url_launcher/url_launcher_platform_interface/test/url_launcher_platform_test.dart @@ -0,0 +1,121 @@ +// Copyright 2013 The Flutter Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +import 'package:flutter_test/flutter_test.dart'; +import 'package:url_launcher_platform_interface/link.dart'; +import 'package:url_launcher_platform_interface/url_launcher_platform_interface.dart'; + +class CapturingUrlLauncher extends UrlLauncherPlatform { + String? url; + bool? useSafariVC; + bool? useWebView; + bool? enableJavaScript; + bool? enableDomStorage; + bool? universalLinksOnly; + Map headers = {}; + String? webOnlyWindowName; + + @override + final LinkDelegate? linkDelegate = null; + + @override + Future launch( + String url, { + required bool useSafariVC, + required bool useWebView, + required bool enableJavaScript, + required bool enableDomStorage, + required bool universalLinksOnly, + required Map headers, + String? webOnlyWindowName, + }) async { + this.url = url; + this.useSafariVC = useSafariVC; + this.useWebView = useWebView; + this.enableJavaScript = enableJavaScript; + this.enableDomStorage = enableDomStorage; + this.universalLinksOnly = universalLinksOnly; + this.headers = headers; + this.webOnlyWindowName = webOnlyWindowName; + + return true; + } +} + +void main() { + test('launchUrl calls through to launch with default options for web URL', + () async { + final CapturingUrlLauncher launcher = CapturingUrlLauncher(); + + await launcher.launchUrl('https://flutter.dev', const LaunchOptions()); + + expect(launcher.url, 'https://flutter.dev'); + expect(launcher.useSafariVC, true); + expect(launcher.useWebView, true); + expect(launcher.enableJavaScript, true); + expect(launcher.enableDomStorage, true); + expect(launcher.universalLinksOnly, false); + expect(launcher.headers, isEmpty); + expect(launcher.webOnlyWindowName, null); + }); + + test('launchUrl calls through to launch with default options for non-web URL', + () async { + final CapturingUrlLauncher launcher = CapturingUrlLauncher(); + + await launcher.launchUrl('tel:123456789', const LaunchOptions()); + + expect(launcher.url, 'tel:123456789'); + expect(launcher.useSafariVC, false); + expect(launcher.useWebView, false); + expect(launcher.enableJavaScript, true); + expect(launcher.enableDomStorage, true); + expect(launcher.universalLinksOnly, false); + expect(launcher.headers, isEmpty); + expect(launcher.webOnlyWindowName, null); + }); + + test('launchUrl calls through to launch with universal links', () async { + final CapturingUrlLauncher launcher = CapturingUrlLauncher(); + + await launcher.launchUrl( + 'https://flutter.dev', + const LaunchOptions( + mode: PreferredLaunchMode.externalNonBrowserApplication)); + + expect(launcher.url, 'https://flutter.dev'); + expect(launcher.useSafariVC, false); + expect(launcher.useWebView, false); + expect(launcher.enableJavaScript, true); + expect(launcher.enableDomStorage, true); + expect(launcher.universalLinksOnly, true); + expect(launcher.headers, isEmpty); + expect(launcher.webOnlyWindowName, null); + }); + + test('launchUrl calls through to launch with all non-default options', + () async { + final CapturingUrlLauncher launcher = CapturingUrlLauncher(); + + await launcher.launchUrl( + 'https://flutter.dev', + const LaunchOptions( + mode: PreferredLaunchMode.externalApplication, + webViewConfiguration: InAppWebViewConfiguration( + enableJavaScript: false, + enableDomStorage: false, + headers: {'foo': 'bar'}), + webOnlyWindowName: 'a_name', + )); + + expect(launcher.url, 'https://flutter.dev'); + expect(launcher.useSafariVC, false); + expect(launcher.useWebView, false); + expect(launcher.enableJavaScript, false); + expect(launcher.enableDomStorage, false); + expect(launcher.universalLinksOnly, false); + expect(launcher.headers['foo'], 'bar'); + expect(launcher.webOnlyWindowName, 'a_name'); + }); +}