Add deep linking page #5244

johnpryan · 2021-02-02T00:37:21Z

This adds instructions for deep linking. There's a few remaining tasks:

check which channel fixes android deeplink to push the path only engine#23255 is available in. (Answer: dev channel)
Verify behavior on iOS
Verify and stage this PR (Still setting up my website build...)
Wait for details on Unable to deep link into Android app flutter#75261 (Fixed by fixes android deeplink query paremeter null crashes engine#24146)

Deployed: https://flutter-website-jr-stagi-988d4.firebaseapp.com/docs/development/ui/navigation/deep-linking

johnpryan · 2021-02-02T02:59:56Z

src/docs/development/ui/navigation/deep-linking.md

+| iOS (not launched)       | App gets initialRoute ("/") and a short time after gets a pushRoute | App gets initialRoute ("/") and a short time after uses the RouteInformationParser to parse the route and call RouterDelegate.setNewRoutePath, which configures the Navigator with the corresponding Page. |
+| Android - (not launched) | App gets initialRoute containing the full route ("http:/deeplink/") | App gets initialRoute ("/deeplink") and passes it to the RouteInformationParser to parse the route and call RouterDelegate.setNewRoutePath, which configures the Navigator with the corresponding Pages.   |
+| iOS (launched)           | pushRoute is called                                                 | Path is parsed, and the Navigator is configured with a new set of Pages.                                                                                                                                   |
+| Android (launched)       | pushRoute is called                                                 | Path is parsed, and the Navigator is configured with a new set of Pages.                                                                                                                                   |


This table currently doesn't look very good, maybe there's a better way to format this?

You are correct. This table doesn't look good. See dart.dev for a pretty table, and see its [implementation](## Keywords) (search for ## Keywords).

sfshaza2

A few nits. When did you want this to be merged? As soon as it's ready? Later?

src/_data/sidenav.yml

sfshaza2 · 2021-02-02T23:14:54Z

src/docs/development/ui/navigation/deep-linking.md

+description: Navigate to routes when the app receives a new URL
+---
+
+Flutter now supports deep linking on iOS and Android. Any link matching the


"now"? As of when? I'd either specify a release or remove "now".

sfshaza2 · 2021-02-02T23:15:21Z

src/docs/development/ui/navigation/deep-linking.md

+---
+
+Flutter now supports deep linking on iOS and Android. Any link matching the
+configured scheme will be handled by the Navigator. By following these steps,


Does this page reflect original navigator or Navigator 2? I think we should be specific.

We're going to refer to Navigator as the Navigator and Navigator 2 as the Router widget for now.

I'll make this code fonted since it's referring to a specific class.

sfshaza2 · 2021-02-02T23:15:49Z

src/docs/development/ui/navigation/deep-linking.md

+
+Flutter now supports deep linking on iOS and Android. Any link matching the
+configured scheme will be handled by the Navigator. By following these steps,
+your app will be able to launch and display routes via named routes (either with


Your app will be able to launch => Your app can launch and...

sfshaza2 · 2021-02-02T23:16:34Z

src/docs/development/ui/navigation/deep-linking.md

+configured scheme will be handled by the Navigator. By following these steps,
+your app will be able to launch and display routes via named routes (either with
+the [`routes`][routes] parameter or [`onGenerateRoute`][onGenerateRoute]), or by
+using the [Router][Router] widget.


It's redundant to put the identical text in both square brackets. In this case, the second pair of square brackets should be empty.

sfshaza2 · 2021-02-02T23:17:28Z

src/docs/development/ui/navigation/deep-linking.md

+
+A full restart is required to apply these changes.
+
+## Test on Android Emulator


Android Emulator => Android emulator

sfshaza2 · 2021-02-02T23:18:21Z

src/docs/development/ui/navigation/deep-linking.md

+</array>
+```
+
+The CFBundleURLName is a unique URL used to distinguish your app from others


All the class names should be code fonted.

sfshaza2 · 2021-02-02T23:18:44Z

src/docs/development/ui/navigation/deep-linking.md

+
+A full restart is required to apply these changes.
+
+## Test on iOS Simulator


iOS Simulator => iOS simulator

sfshaza2 · 2021-02-02T23:19:58Z

src/docs/development/ui/navigation/deep-linking.md

+## Migrating from plugin-based deep linking
+
+If you have written a plugin to handle deep links, as described in [this
+article][plugin-linking], it will continue to work until you opt-in to this


OK, it is Very Bad Form to link on "this". You've done that twice in this page. Use the name of the article or at least some descriptive text in the link text.

sfshaza2 · 2021-02-02T23:25:33Z

src/docs/development/ui/navigation/deep-linking.md

+| iOS (not launched)       | App gets initialRoute ("/") and a short time after gets a pushRoute | App gets initialRoute ("/") and a short time after uses the RouteInformationParser to parse the route and call RouterDelegate.setNewRoutePath, which configures the Navigator with the corresponding Page. |
+| Android - (not launched) | App gets initialRoute containing the full route ("http:/deeplink/") | App gets initialRoute ("/deeplink") and passes it to the RouteInformationParser to parse the route and call RouterDelegate.setNewRoutePath, which configures the Navigator with the corresponding Pages.   |
+| iOS (launched)           | pushRoute is called                                                 | Path is parsed, and the Navigator is configured with a new set of Pages.                                                                                                                                   |
+| Android (launched)       | pushRoute is called                                                 | Path is parsed, and the Navigator is configured with a new set of Pages.                                                                                                                                   |


You are correct. This table doesn't look good. See dart.dev for a pretty table, and see its [implementation](## Keywords) (search for ## Keywords).

johnpryan · 2021-02-03T00:22:52Z

Since this is currently on the dev channel, could we merge it with note at the top of the page? (waiting is okay, too)

sfshaza2 · 2021-02-03T00:49:18Z

Whaaaaaaa?! But Flutter already has a Router class, right? This is confusing.

…

On Tue, Feb 2, 2021 at 4:47 PM John Ryan ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In src/docs/development/ui/navigation/deep-linking.md <#5244 (comment)>: > @@ -0,0 +1,116 @@ +--- +title: Deep linking +description: Navigate to routes when the app receives a new URL +--- + +Flutter now supports deep linking on iOS and Android. Any link matching the +configured scheme will be handled by the Navigator. By following these steps, We're going to refer to Navigator as the Navigator and Navigator 2 as the Router widget for now. — You are receiving this because your review was requested. Reply to this email directly, view it on GitHub <#5244 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AKS4PKOPR5JOQBX2DBDXKSTS5CMLPANCNFSM4W5W4T5A> .

sfshaza2 · 2021-02-03T01:03:23Z

Yes, I am definitely ok with adding a note about this being on the dev channel. On flutter.dev/docs, we say:

The documentation on this site reflects the latest stable release of Flutter.

So it's well and good to add a warning and publish anyway.

- Use code font for class names - Avoid "this" in link names - Use title case - Improve table formatting - Add note that this is only available on the dev or master channels

johnpryan · 2021-02-03T01:21:12Z

Ready for another look: https://flutter-website-jr-stagi-988d4.firebaseapp.com/docs/development/ui/navigation/deep-linking

src/docs/development/ui/navigation/deep-linking.md

sfshaza2

We're getting there. :)

src/_data/sidenav.yml

sfshaza2 · 2021-02-03T16:40:14Z

src/docs/development/ui/navigation/deep-linking.md

+---
+
+{{site.alert.note}}
+This feature is only available on the dev or master channel. See [Switching


This is a minor nit, but we indent notes by 2 spaces at the beginning of each line, but not the site.alert.tag tag itself.

sfshaza2 · 2021-02-03T16:42:22Z

src/docs/development/ui/navigation/deep-linking.md

+Flutter channels][switching-channels] for more information.
+{{site.alert.end}}
+
+Flutter supports deep linking on iOS and Android in the dev channel. Any link


It supports it on web, too. And desktop? If I read that first sentence, I might stop reading there if I'm not programming specifically for mobile. I'd like to minimize changes that we might have to. make later, so please address web and desktop, if possible, now. The first paragraph should indicate whether they need to keep reading.

I'll add web to this sentence. The second paragraph discusses web behavior.

sfshaza2 · 2021-02-03T16:44:21Z

src/docs/development/ui/navigation/deep-linking.md

+{{site.alert.end}}
+
+Flutter supports deep linking on iOS and Android in the dev channel. Any link
+matching the configured scheme will be handled by the `Navigator`. By following


"Any link matching the configured scheme will be handled by the Navigator."

That sentence is fairly confusing, and it's in passive tense. Do you mean:

"The Navigator handles deep linking." ?? But this doesn't really seem right.

I decided to replace this sentence with a softer explanation " Users opening a URL will display a specific screen in your app."

sfshaza2 · 2021-02-03T16:46:18Z

src/docs/development/ui/navigation/deep-linking.md

+A full restart is required to apply these changes.
+
+## Test on Android emulator
+To test with an Android emulator, the `adb` command can be given an intent. The


"can be given an intent" => To test..., give the adb command an intent where the host name matches the name defined in AndroidManifest.xml. For example:

sfshaza2 · 2021-02-03T16:48:01Z

src/docs/development/ui/navigation/deep-linking.md

+A full restart is required to apply these changes.
+
+## Test on iOS simulator
+The `xcrun` command can be used to test on the iOS Simulator:


Again, very passive wording.

=> "Use the xcrun command to test on the ..."

src/docs/development/ui/navigation/deep-linking.md

sfshaza2 · 2021-02-03T17:10:36Z

src/docs/development/ui/navigation/deep-linking.md

+matching the configured scheme will be handled by the `Navigator`. By following
+these steps, your can launch and display routes via named routes (either with
+the [`routes`][routes] parameter or [`onGenerateRoute`][onGenerateRoute]), or by
+using the [Router][] widget.


Given that we've publicly called the new mechanism Navigator 2, we need to be clear what we are talking about here. This needs another note. (I can't remember exactly what you said about the naming, but we need to be clear and I haven't seen this said anywhere else.) Something along the lines of.

{{site.alert.secondary}} **Version note:** You might be familiar with [Navigator 2.0][]. When referring to the updated navigator mechanism, we now call it..." {{site.alert.end}}

Will try to get an answer on this.

johnpryan · 2021-02-03T18:44:06Z

This is almost ready for another look - I'll spend some time figuring out what the team would like to call Navigator 2 going forward.

johnpryan · 2021-02-03T20:18:39Z

Ready for another look.

sfshaza2

LGTM, if you accept the suggestions.

src/docs/development/ui/navigation/deep-linking.md

sfshaza2 · 2021-02-04T21:29:52Z

src/docs/development/ui/navigation/deep-linking.md

+[switching-channels]: /docs/development/tools/sdk/upgrading#switching-flutter-channels
+[routes]: https://api.flutter.dev/flutter/material/MaterialApp/routes.html
+[onGenerateRoute]: https://api.flutter.dev/flutter/material/MaterialApp/onGenerateRoute.html
+[Router]: https://api.flutter.dev/flutter/widgets/Router-class.html
+[Navigator 2.0]: https://medium.com/flutter/learning-flutters-new-navigation-and-routing-system-7c9068155ade
+[intent filter]: https://developer.android.com/guide/components/intents-filters
+[plugin-linking]: https://medium.com/flutter-community/deep-links-and-flutter-applications-how-to-handle-them-properly-8c9865af9283
+[verify-android-links]: https://developer.android.com/training/app-links/verify-site-associations
+[router-sample]: https://github.com/flutter/samples/blob/master/navigation_and_routing/lib/nav_2/router.dart


Suggested change

[switching-channels]: /docs/development/tools/sdk/upgrading#switching-flutter-channels

[routes]: https://api.flutter.dev/flutter/material/MaterialApp/routes.html

[onGenerateRoute]: https://api.flutter.dev/flutter/material/MaterialApp/onGenerateRoute.html

[Router]: https://api.flutter.dev/flutter/widgets/Router-class.html

[Navigator 2.0]: https://medium.com/flutter/learning-flutters-new-navigation-and-routing-system-7c9068155ade

[intent filter]: https://developer.android.com/guide/components/intents-filters

[plugin-linking]: https://medium.com/flutter-community/deep-links-and-flutter-applications-how-to-handle-them-properly-8c9865af9283

[verify-android-links]: https://developer.android.com/training/app-links/verify-site-associations

[router-sample]: https://github.com/flutter/samples/blob/master/navigation_and_routing/lib/nav_2/router.dart

[switching-channels]: /docs/development/tools/sdk/upgrading#switching-flutter-channels

[routes]: {{site.api}}/flutter/material/MaterialApp/routes.html

[onGenerateRoute]: {{site.api}}/flutter/material/MaterialApp/onGenerateRoute.html

[Router]: {{site.api}}/flutter/widgets/Router-class.html

[Navigator 2.0]: {{site.flutter-medium}}/flutter/learning-flutters-new-navigation-and-routing-system-7c9068155ade

[intent filter]: https://developer.android.com/guide/components/intents-filters

[plugin-linking]: {{site.medium}}/flutter-community/deep-links-and-flutter-applications-how-to-handle-them-properly-8c9865af9283

[verify-android-links]: https://developer.android.com/training/app-links/verify-site-associations

[router-sample]: {{site.github}}/flutter/samples/blob/master/navigation_and_routing/lib/nav_2/router.dart

src/docs/development/ui/navigation/deep-linking.md

Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]>

johnpryan · 2021-02-04T23:15:31Z

Ready for another look: https://flutter-website-jr-stagi-988d4.firebaseapp.com/docs/development/ui/navigation/deep-linking

johnpryan · 2021-02-08T22:07:23Z

Whoops, this is LGTM'd already. Merging...

* add deep linking article, move navigation.md to navigation/index.md * Change table title * add deep linking page to sidenav * fix sidenav bug * specify deep linking is supported in the dev channel * "be able to launch" -> "can launch" * simplify reference-style links * Address review comments - Use code font for class names - Avoid "this" in link names - Use title case - Improve table formatting - Add note that this is only available on the dev or master channels * indent note * add web browsers to supported platforms in first paragraph * simplify introduction * active voice * active voice * add Navigator 2.0 warning - renamed to Router. * Update src/docs/development/ui/navigation/deep-linking.md Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]> * Apply suggestions from code review Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]> * remove redundant sentence * end sentence correctly * keep 80 column limit * 80 column limit * 80 column limit Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]>

add deep linking article, move navigation.md to navigation/index.md

1d65b29

google-cla bot added the cla: yes Contributor has signed the Contributor License Agreement label Feb 2, 2021

johnpryan requested a review from sfshaza2 February 2, 2021 00:37

Change table title

65a17a3

johnpryan commented Feb 2, 2021

View reviewed changes

add deep linking page to sidenav

bb1d55d

sfshaza2 requested changes Feb 3, 2021

View reviewed changes

johnpryan added 3 commits February 2, 2021 16:41

fix sidenav bug

7a30935

specify deep linking is supported in the dev channel

0a61817

"be able to launch" -> "can launch"

b9be9ac

simplify reference-style links

e8679fe

Address review comments

b171edf

- Use code font for class names - Avoid "this" in link names - Use title case - Improve table formatting - Add note that this is only available on the dev or master channels

sarbagyastha suggested changes Feb 3, 2021

View reviewed changes

src/docs/development/ui/navigation/deep-linking.md Show resolved Hide resolved

sfshaza2 requested changes Feb 3, 2021

View reviewed changes

johnpryan added 5 commits February 3, 2021 10:30

indent note

5d4d59c

add web browsers to supported platforms in first paragraph

c095fe7

simplify introduction

27d40c3

active voice

9e2877f

active voice

a9f872f

add Navigator 2.0 warning - renamed to Router.

c621111

Merge branch 'master' of github.com:flutter/website into deep-linking

b90e153

sfshaza2 approved these changes Feb 4, 2021

View reviewed changes

johnpryan and others added 2 commits February 4, 2021 15:04

Update src/docs/development/ui/navigation/deep-linking.md

0ce8a03

Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]>

Apply suggestions from code review

84960e4

Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]>

johnpryan added 5 commits February 4, 2021 15:09

remove redundant sentence

6786f44

end sentence correctly

e60146f

keep 80 column limit

740bc72

80 column limit

02c2100

80 column limit

97b5b63

johnpryan merged commit 027bacc into flutter:master Feb 8, 2021


		A full restart is required to apply these changes.

		## Test on Android Emulator


		A full restart is required to apply these changes.

		## Test on iOS Simulator

Add deep linking page #5244

Add deep linking page #5244

Uh oh!

Conversation

johnpryan commented Feb 2, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sfshaza2 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johnpryan commented Feb 3, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sfshaza2 commented Feb 3, 2021 via email

Uh oh!

sfshaza2 commented Feb 3, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

johnpryan commented Feb 3, 2021

Uh oh!

Uh oh!

sfshaza2 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johnpryan commented Feb 3, 2021

Uh oh!

johnpryan commented Feb 3, 2021

Uh oh!

sfshaza2 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

johnpryan commented Feb 2, 2021 •

edited

Loading

johnpryan commented Feb 3, 2021 •

edited

Loading

sfshaza2 commented Feb 3, 2021 •

edited

Loading