[url_launcher] Adds documentation that a launch needs to be triggered…

… by a user action (#5143)

Some web browsers, such as Safari, may prevent URL launching if it is not triggered by a user action (e.g. a button click). Even if a user triggers a launch through a button click, if there is a delay due to awaiting a Future before the launch, the browser may still block it. This can be confusing if you don't know it. As flutter/flutter#78524 suggested, should this be documented. Therefore, I added a few sentences to the `launchUrl`.

Please let me know if this documentation is too long or not the right place.

Fixes flutter/flutter#78524

packages/url_launcher/url_launcher/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 6.2.2
+
+* Adds a link about web limitations to the `url_launcher_web` package in the
+  `url_launcher` `README.md` and `launchUrl` method.
+
 ## 6.2.1
 
 * Fixes incorrect types in `supportsLaunchMode` and

packages/url_launcher/url_launcher/README.md

@@ -98,6 +98,13 @@ See
 [the Android documentation](https://developer.android.com/training/package-visibility/use-cases)
 for examples of other queries.
 
+### Web
+
+Some web browsers may have limitations (e.g. a launch must be triggered by a
+user action). Check
+[package:url_launcher_web](https://pub.dev/packages/url_launcher_web#limitations-on-the-web-platform)
+for more web-specific information.
+
 ## Supported URL schemes
 
 The provided URL is passed directly to the host platform for handling. The

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

@@ -29,6 +29,11 @@ import 'type_conversion.dart';
 ///  - "_self" opens the new URL in the current tab.
 /// Default behaviour when unset is to open the url in a new tab.
 ///
+/// Web browsers prevent launching URLs in a new tab/window, unless
+/// triggered by a user action (e.g. a button click). See
+/// [package:url_launcher_web](https://pub.dev/packages/url_launcher_web#limitations-on-the-web-platform)
+/// for more details.
+///
 /// Returns true if the URL was launched successful, otherwise either returns
 /// false or throws a [PlatformException] depending on the failure.
 Future<bool> launchUrl(

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.2.1
+version: 6.2.2
 
 environment:
   sdk: ">=3.1.0 <4.0.0"

packages/url_launcher/url_launcher_web/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.2.2
+
+* Adds documentation that a launch in a new window/tab needs to be triggered by
+  a user action.
+
 ## 2.2.1
 
 * Supports Flutter Web + Wasm

packages/url_launcher/url_launcher_web/README.md

@@ -13,3 +13,21 @@ should add it to your `pubspec.yaml` as usual.
 
 [1]: https://pub.dev/packages/url_launcher
 [2]: https://flutter.dev/docs/development/packages-and-plugins/developing-packages#endorsed-federated-plugin
+
+## Limitations on the Web platform
+
+### A launch needs to be triggered by a user action
+
+Web browsers prevent launching URLs in a new tab/window, unless triggered by a
+user action (e.g. a button click).
+
+Even if a user triggers a launch through a button click, if there is a delay due
+to awaiting a Future before the launch, the browser may still block it. This is
+because the browser might perceive the launch as not being a direct result of
+user interaction, particularly if the Future takes too long to complete.
+
+In such cases, you can use the `webOnlyWindowName` parameter, setting it to
+`_self`, to open the URL within the current tab. Another approach is to ensure
+that the `uri` is synchronously ready.
+
+Read more: MDN > [Transient activation](https://developer.mozilla.org/en-US/docs/Glossary/Transient_activation).

packages/url_launcher/url_launcher_web/pubspec.yaml

@@ -2,7 +2,7 @@ name: url_launcher_web
 description: Web platform implementation of url_launcher
 repository: https://github.com/flutter/packages/tree/main/packages/url_launcher/url_launcher_web
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+url_launcher%22
-version: 2.2.1
+version: 2.2.2
 
 environment:
   sdk: ^3.2.0