[url_launcher] Adds documentation that a launch needs to be triggered by a user action #5143

nilsreichardt · 2023-10-13T17:50:43Z

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

Pre-launch Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

… by a user action

ditman · 2023-10-13T17:58:28Z

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

 ///  - "_self" opens the new URL in the current tab.
 /// Default behaviour when unset is to open the url in a new tab.
 ///
+/// Some web browsers, such as Safari, may prevent URL launching if it is not


I normally add these notes to the README of the web package under a "Limitations of the web platform" section (example, very similar to the Autoplay problem!), but I'm not sure if those are discoverable enough, since they're by default "hidden" in pub

Yes, I agree that it's a bit hidden and the README.md would also a good place 👍 If you or @stuartmorgan like the approach with README.md more, I could copy the structure of the video_player package (having a short note that there are limitations on web in the main README and a more detailed description in url_launcher_web package).

I think putting the long explanation in the README and then referencing that here is probably the best option.

I made the following changes:

Adding a link about the web limitations in the "Configuration" section of the README.md of url_launcher (like video_player has), please let me know if this is the wrong location

Adding a new section "Limitations on the Web platform" with the detailed documentation in the README.md of the url_launcher_web package

Just referencing to this limitation in the launchUrl method

stuartmorgan-g

Looks good to me with nits, but @ditman should do the main review.

stuartmorgan-g · 2023-11-01T14:08:09Z

packages/url_launcher/url_launcher_web/README.md

+
+### A launch needs to be triggered by a user action
+
+Some web browsers, such as Safari, may prevent URL launching if it is not triggered by a user action (e.g. a button click).


Nit: We generally try to wrap our markdown files at about 80 characters; could you wrap all of these long lines?

stuartmorgan-g · 2023-11-01T14:09:01Z

packages/url_launcher/url_launcher_web/README.md

+
+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.


This is directly about the same thing as the previous text, so should not be a new paragraph.

…ch-url-method

nilsreichardt · 2023-12-03T11:15:50Z

@ditman I applied the suggestions by @stuartmorgan and resolved the merge conflicts 👍 It's ready for review :)

ditman

Hey @nilsreichardt, I left a few tweaks to the docs and a link to a relevant page of the MDN, lmk if my changes make sense to you. We can land this once you adopt those changes (or something similar). Important to say that this is definitely not a safari-only thing, all browsers are doing this.

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

packages/url_launcher/url_launcher_web/README.md

packages/url_launcher/url_launcher_web/CHANGELOG.md

Co-authored-by: David Iglesias <[email protected]>

nilsreichardt · 2023-12-08T07:35:59Z

@ditman Thanks for the suggestions ❤️ LGTM

ditman · 2023-12-08T15:07:21Z

Thanks! I've restarted a couple of flaky checks, and will apply autosubmit. This should land today.

…riggered by a user action (flutter/packages#5143)

flutter/packages@6cd0657...cb6dbcd 2023-12-09 [email protected] [multicast_dns] Adjust README (flutter/packages#5529) 2023-12-09 [email protected] [tool] Use ^ for Dart SDK (flutter/packages#5623) 2023-12-09 [email protected] [google_sign_in_web] Migrate to pkg:web. (flutter/packages#5612) 2023-12-08 [email protected] [google_maps_flutter] Disable failing iOS tests (flutter/packages#5629) 2023-12-08 [email protected] Add `parse` constructors for the `BenchmarkResults` and `BenchmarkScore` classes (flutter/packages#5614) 2023-12-08 [email protected] [path_provider_android] Disable `getExternalStorageDirectories (type: ...)` test (flutter/packages#5619) 2023-12-08 [email protected] [ci] Fix indentation in labeler.yml (flutter/packages#5625) 2023-12-08 [email protected] Update labeler to 5.0.0, fix yml format (flutter/packages#5580) 2023-12-08 [email protected] [url_launcher] Adds documentation that a launch needs to be triggered by a user action (flutter/packages#5143) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages-flutter-autoroll Please CC [email protected],[email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Flutter: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md

nilsreichardt added 4 commits October 13, 2023 19:44

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

371edf5

… by a user action

Fix comment

f64dcc9

Format comment

ad9ddd9

Change action and launch

bcbc28d

nilsreichardt requested a review from stuartmorgan-g as a code owner October 13, 2023 17:50

github-actions bot added the p: url_launcher label Oct 13, 2023

ditman reviewed Oct 13, 2023

View reviewed changes

Add documentation to the README.md

754fc27

github-actions bot added the platform-web label Oct 13, 2023

nilsreichardt and others added 3 commits October 13, 2023 21:00

Escape README.md in changelog

cbcb38d

Fix typo

d88d1f5

Merge branch 'main' into add-docs-for-the-launch-url-method

4a63496

stuartmorgan-g approved these changes Nov 1, 2023

View reviewed changes

nilsreichardt added 2 commits December 1, 2023 09:18

Format README.md and remove paragraph

7dd42b9

Merge remote-tracking branch 'origin/main' into add-docs-for-the-laun…

309f5d8

…ch-url-method

nilsreichardt requested a review from ditman December 3, 2023 11:15

Merge branch 'main' into add-docs-for-the-launch-url-method

510b85a

ditman approved these changes Dec 7, 2023

View reviewed changes

nilsreichardt and others added 7 commits December 8, 2023 08:30

Update packages/url_launcher/url_launcher_web/CHANGELOG.md

db20525

Co-authored-by: David Iglesias <[email protected]>

Update packages/url_launcher/url_launcher_web/README.md

043816d

Co-authored-by: David Iglesias <[email protected]>

Update packages/url_launcher/url_launcher_web/README.md

5234fb8

Co-authored-by: David Iglesias <[email protected]>

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

3a03cff

Co-authored-by: David Iglesias <[email protected]>

Update packages/url_launcher/url_launcher_web/README.md

a76f52a

Co-authored-by: David Iglesias <[email protected]>

Format Markdown file

8d140e5

Merge branch 'main' into add-docs-for-the-launch-url-method

8b0e995

ditman added the autosubmit Merge PR when tree becomes green via auto submit App label Dec 8, 2023

auto-submit bot merged commit e848d62 into flutter:main Dec 8, 2023

engine-flutter-autoroll mentioned this pull request Dec 11, 2023

Roll Packages from 6cd0657c4500 to cb6dbcdd2305 (9 revisions) flutter/flutter#139911

Merged

engine-flutter-autoroll added a commit to engine-flutter-autoroll/flutter that referenced this pull request Dec 11, 2023

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

fa62355

…riggered by a user action (flutter/packages#5143)

reidbaker mentioned this pull request Jan 12, 2024

Dialog Debug #5881

Closed

reidbaker mentioned this pull request Jan 19, 2024

[in_app_purchase] Add play country code api #5941

Merged

12 tasks

reidbaker mentioned this pull request Feb 19, 2024

[in_app_purchase_android] Add UserChoiceBilling mode. #6162

Merged

16 tasks


		### A launch needs to be triggered by a user action

		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 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.

[url_launcher] Adds documentation that a launch needs to be triggered by a user action #5143

[url_launcher] Adds documentation that a launch needs to be triggered by a user action #5143

Uh oh!

Conversation

nilsreichardt commented Oct 13, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

ditman Oct 13, 2023

Choose a reason for hiding this comment

Uh oh!

nilsreichardt Oct 13, 2023

Choose a reason for hiding this comment

Uh oh!

stuartmorgan-g Oct 13, 2023

Choose a reason for hiding this comment

Uh oh!

nilsreichardt Oct 13, 2023

Choose a reason for hiding this comment

Uh oh!

stuartmorgan-g left a comment

Choose a reason for hiding this comment

Uh oh!

stuartmorgan-g Nov 1, 2023

Choose a reason for hiding this comment

Uh oh!

stuartmorgan-g Nov 1, 2023

Choose a reason for hiding this comment

Uh oh!

nilsreichardt commented Dec 3, 2023

Uh oh!

ditman left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nilsreichardt commented Dec 8, 2023

Uh oh!

ditman commented Dec 8, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nilsreichardt commented Oct 13, 2023 •

edited

Loading

ditman left a comment •

edited

Loading