Migration guide for `RouteInformation.location`

Summary

RouteInformation.location and related APIs were deprecated in the favor of RouteInformation.uri.

Context

The RouteInformation needs the authority information to handle mobile deeplinks from different web domains. The uri field was added to RouteInformation that captures the entire deeplink information and route-related parameters were converted to the full Uri format. This led to deprecation of incompatible APIs.

Description of change

• The RouteInformation.location was replaced by RouteInformation.uri.
• The WidgetBindingObserver.didPushRoute was deprecated.
• The location parameter of SystemNavigator.routeInformationUpdated was replaced by the newly added uri parameter.

Migration guide

Code before migration:

const RouteInformation myRoute = RouteInformation(location: '/myroute');

Code after migration:

final RouteInformation myRoute = RouteInformation(uri: Uri.parse('/myroute'));

Code before migration:

final String myPath = myRoute.location;

Code after migration:

final String myPath = myRoute.uri.path;

Code before migration:

class MyObserverState extends State<MyWidget> with WidgetsBindingObserver {
  @override
  Future<bool> didPushRoute(String route) => _handleRoute(route);
}

Code after migration:

class MyObserverState extends State<MyWidget> with WidgetsBindingObserver {
  @override
  Future<bool> didPushRouteInformation(RouteInformation routeInformation) => _handleRoute(
    Uri.decodeComponent(
      Uri(
        path: uri.path.isEmpty ? '/' : uri.path,
        queryParameters: uri.queryParametersAll.isEmpty ? null : uri.queryParametersAll,
        fragment: uri.fragment.isEmpty ? null : uri.fragment,
      ).toString(),
    )
  );
}

Code before migration:

SystemNavigator.routeInformationUpdated(location: '/myLocation');

Code after migration:

SystemNavigator.routeInformationUpdated(uri: Uri.parse('/myLocation'));

Timeline

Landed in version: 3.10.0-13.0.pre
In stable release: 3.13.0

References

Relevant PRs:

• PR 119968: Implement url support for RouteInformation and didPushRouteInformation.