From e848d620976a0511c08c26a0a3d8ef7cf333aa66 Mon Sep 17 00:00:00 2001 From: Nils Reichardt Date: Fri, 8 Dec 2023 16:17:57 +0100 Subject: [PATCH] [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 https://github.com/flutter/flutter/issues/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 https://github.com/flutter/flutter/issues/78524 --- .../url_launcher/url_launcher/CHANGELOG.md | 5 +++++ packages/url_launcher/url_launcher/README.md | 7 +++++++ .../url_launcher/lib/src/url_launcher_uri.dart | 5 +++++ .../url_launcher/url_launcher/pubspec.yaml | 2 +- .../url_launcher/url_launcher_web/CHANGELOG.md | 5 +++++ .../url_launcher/url_launcher_web/README.md | 18 ++++++++++++++++++ .../url_launcher/url_launcher_web/pubspec.yaml | 2 +- 7 files changed, 42 insertions(+), 2 deletions(-) diff --git a/packages/url_launcher/url_launcher/CHANGELOG.md b/packages/url_launcher/url_launcher/CHANGELOG.md index db1516640df6..c1523e11d150 100644 --- a/packages/url_launcher/url_launcher/CHANGELOG.md +++ b/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 diff --git a/packages/url_launcher/url_launcher/README.md b/packages/url_launcher/url_launcher/README.md index bb69a52fb91f..642346f97010 100644 --- a/packages/url_launcher/url_launcher/README.md +++ b/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 diff --git a/packages/url_launcher/url_launcher/lib/src/url_launcher_uri.dart b/packages/url_launcher/url_launcher/lib/src/url_launcher_uri.dart index 23ea836b7406..d91558a673a8 100644 --- a/packages/url_launcher/url_launcher/lib/src/url_launcher_uri.dart +++ b/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 launchUrl( diff --git a/packages/url_launcher/url_launcher/pubspec.yaml b/packages/url_launcher/url_launcher/pubspec.yaml index c68c8a129f39..3a5c71ea9a30 100644 --- a/packages/url_launcher/url_launcher/pubspec.yaml +++ b/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" diff --git a/packages/url_launcher/url_launcher_web/CHANGELOG.md b/packages/url_launcher/url_launcher_web/CHANGELOG.md index 34ae8c8b8861..ed6042312a10 100644 --- a/packages/url_launcher/url_launcher_web/CHANGELOG.md +++ b/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 diff --git a/packages/url_launcher/url_launcher_web/README.md b/packages/url_launcher/url_launcher_web/README.md index bcea84855915..f186d7a49bb8 100644 --- a/packages/url_launcher/url_launcher_web/README.md +++ b/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). \ No newline at end of file diff --git a/packages/url_launcher/url_launcher_web/pubspec.yaml b/packages/url_launcher/url_launcher_web/pubspec.yaml index 0c3b8ea0821b..371c534a20de 100644 --- a/packages/url_launcher/url_launcher_web/pubspec.yaml +++ b/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