setInitialRoute is broken for iOS add-to-app

[mehmetf]

b/159359456

https://flutter.dev/docs/development/add-to-app/ios/add-flutter-screen?tab=entrypoint-library-swift-tab#route recommends

FlutterEngine *flutterEngine =
    [[FlutterEngine alloc] initWithName:@"my flutter engine"];
[[flutterEngine navigationChannel] invokeMethod:@"setInitialRoute"
                                      arguments:@"/onboarding"];
[flutterEngine run];

This does not work. The initial route comes out as default ("/"). If I initialize view controller with project (instead of engine) and use [flutterViewController setInitialRoute], it works.

[Hixie]

@chinmaygarde says this is more or less working as intended and that there is a workaround so I will reduce it to P3; he will update this bug shortly.

[chinmaygarde]

@mehmetf : So, I am not sure how the initial recommendation on the page you linked was made. It is definitely inaccurate. Channel setup has always occurred when the underlying shell in the engine is setup. In the FlutterEngine API, the shell isn't setup till the runWithEntrypoint:libraryURI: method is called. So, I am pretty sure [flutterEngine navigationChannel] result is nil. Looking back at the history, it seems to have always worked this way with the FlutterViewController being special cased to setup the shell (and it channels) upfront to specifically work around the issue of the navigation channel being unavailable. The fix is to do the same in FlutterEngine (i.e, create the shell with Settings object in the FlutterDartProject).

The behavior described in the docs is a fair ask but it is a bit mystifying how that recommendation was made when the implementation has never worked that way. In any case, I see you bumped up the priority of this to P1. Is this now a blocker? My reading of the internal issue indicated that there was a workaround. I'll have reprioritize some other stuff if this is at indicated priority.

[mehmetf]

It is definitely inaccurate.

FWIW, I was very surprised at that recommendation as well.

Are you referring to initialize view controller with project instead of engine workaround? If so, that does not work for the user since they are an add-to-app user who wants to control how/when engine is initialized.

However, it is not a launch blocker for them for now so lowering priority to P2. We should, at the very least, fix documentation asap tho.

[chinmaygarde]

Are you referring to initialize view controller with project instead of engine workaround? If so, that does not work...

Yes. Ok. This would be a blocker for them eventually because there is no way in the current API to send a message before the run call. The UIViewController manages this today because it makes a private call to the engine to create its shell and setup channels. I'll find an owner for this in the next triage run.

[xster]

ah yes, the docs are totally off. I'm surprised no one ran into this so far.

We have this on Android https://flutter.dev/docs/development/add-to-app/android/add-flutter-screen#initial-route-with-a-cached-engine and implemented channel buffers to fix timing issues flutter/engine#12167 but we didn't change the loading sequence on iOS.

Haven't decided how to fix this yet but I'm tempted to fix the loading sequence discrepancy between Android and iOS which causes unnecessary confusion https://flutter.dev/docs/development/add-to-app/performance#starting-the-dart-vm.

[xster]

Actually that doesn't also fix the other root issue that the whole setInitialRoute API is incredibly confusing. I think we made slight progress in making it less of a footgun building it into the FlutterActivity builder pattern. I'm going to repeat the same thing here:

1- Deprecate the FlutterViewController setInitialRoute API which needs to be called at a (very fleeting) specific moment.
2- Add a constructor to iOS FlutterEngine and FlutterViewController to save an initial route to be used when running.
3- Once you set an initial route, you can never change it. There may be valid cases but it's already incredibly difficult to pull off today. On UIViewController/Activities, there's theoretically no time between creation and displaying it (at which point the initial route is "committed") to change it. On FlutterEngine, there's also no strong reasons to construct an engine and not run it (at which point the initial route is "committed"). There will continue to be documentation for how to push/pop the route on a cached engine on Android and iOS.

This fixes 2 issues with one code change.

[chinmaygarde]

@xster I am bumping the milestone for this as the month is out. Please re-adjust as necessary if you think the linked patch cannot land by then.

[xster]

yup, thanks

[xster]

mini update: about the land fix PR

[lds8988]

@xster when this fix will merge to stable channel?

[xster]

Did you mean 1.21? We're currently not planning to. Are you blocked on this issue?

[lds8988]

@xster yes. My app's feature should jump to flutter page from native page, but setInitialRoute not work so that can not jump to specified page.Is it possible release a 1.20.2 to fix this bug?

[xster]

Reverted. Reworking tests.

[xster]

@lds8988 it's a non-trivial refactor so we're not going to make a cherry pick on the stable branch. Please wait for the 1.22 release.

In the meantime, if you're blocked, consider the following workarounds:

1. Use a Dart entrypoint to customize the initial Flutter screen https://flutter.dev/docs/development/add-to-app/ios/add-flutter-screen?tab=engine-swift-tab#dart-entrypoint.
2. Use [[flutterEngine navigationChannel] invokeMethod:@"pushRoute" arguments:route]; if needed. This creates 2 routes instead of 1 in Flutter but you can control the foremost visible route.

[lds8988]

@xster I'll try it. Thx for reply.

[murtuzasaify]

@xster I am facing the same problem, setting initial route on engines navigation channel has no impact and eventually had to navigate to desired screen without warming up the engine.
Any info on when the pull request for handling initial route on engine be merged and available ?

[xster]

It's already on master. I'll add more documentation on it once it's on stable channel in about a month. In the meantime, you can probably figure out how to use the new APIs from the headers. (e.g. use the specific run selectors on the FlutterEngine to specify the initial route when running the engine initially).

[murtuzasaify]

thanks @xster , I can see that you introduced - (BOOL)runWithEntrypoint:(NSString*)entrypoint initialRoute:(NSString*)initialRoute which can now be used to set initial route.
How can I consume and test this currently, if I point to master branch of Flutter pod (pod Flutter, branch: master) will this be available ?

[xster]

No, you should flutter channel master flutter upgrade instead if you want to try this on master.

[jzyds]

Is this fixed already in 1.22.0-1.0.pre?

How to initialRoute with arguments?

[Senasiko]

@lds8988 it's a non-trivial refactor so we're not going to make a cherry pick on the stable branch. Please wait for the 1.22 release.

In the meantime, if you're blocked, consider the following workarounds:

1. Use a Dart entrypoint to customize the initial Flutter screen https://flutter.dev/docs/development/add-to-app/ios/add-flutter-screen?tab=engine-swift-tab#dart-entrypoint.
2. Use [[flutterEngine navigationChannel] invokeMethod:@"pushRoute" arguments:route]; if needed. This creates 2 routes instead of 1 in Flutter but you can control the foremost visible route.

What should I do to control the foremost visible route? If I use [[flutterEngine navigationChannel] invokeMethod:@"pushRoute" arguments:route]; and Navigator.pop() in flutter view, I will go back to the initialRoute or home, not the view in app.

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of flutter doctor -v and a minimal reproduction of the issue.