From 9bb85914e6998dd54a07322d41da0a6bae6372e1 Mon Sep 17 00:00:00 2001 From: Joonas Kerttula Date: Thu, 7 Nov 2024 11:01:25 +0200 Subject: [PATCH] chore: include navigation initialization in readme (#330) --- README.md | 168 +++++++++++++++++--- example/src/App.tsx | 4 +- example/src/controls/navigationControls.tsx | 4 +- 3 files changed, 151 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 78fe757..50e6cfa 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,6 @@ To set up, specify your API key in the application delegate `ios/Runner/AppDeleg - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [GMSServices provideAPIKey:@"API_KEY"]; - [GMSServices setMetalRendererEnabled:YES]; return [super application:application didFinishLaunchingWithOptions:launchOptions]; } @@ -73,6 +72,131 @@ To set up, specify your API key in the application delegate `ios/Runner/AppDeleg ## Usage +### Initializing Navigation +Wrap application with the `NavigationProvider` component. This will provide the necessary context for navigation throughout your app. + +```tsx +import React from 'react'; +import { + NavigationProvider, + TaskRemovedBehavior, + type TermsAndConditionsDialogOptions, +} from '@googlemaps/react-native-navigation-sdk'; + +const termsAndConditionsDialogOptions: TermsAndConditionsDialogOptions = { + title: 'Terms and Conditions Title', + companyName: 'Your Company Name', + showOnlyDisclaimer: true, +}; + +const App = () => { + return ( + + {/* Add your application components here */} + + ); +}; + +export default App; +``` + +#### Task Removed Behavior + +The `taskRemovedBehavior` prop defines how the navigation should behave when a task is removed from the recent apps list on Android. It can either: + +- `CONTINUE_SERVICE`: Continue running in the background. (default) +- `QUIT_SERVICE`: Shut down immediately. + +This prop has only an effect on Android. + +### Using NavigationController + +You can use the `useNavigation` hook to access the `NavigationController` and control navigation within your components. The `useNavigation` hook also provides methods to add and remove listeners. + +#### Initializing Navigation + +```tsx +... +const { navigationController } = useNavigation(); + +const initializeNavigation = useCallback(async () => { + try { + await navigationController.init(); + console.log('Navigation initialized'); + } catch (error) { + console.error('Error initializing navigation', error); + } +}, [navigationController]); +``` + +> [!NOTE] +> Navigation can be controlled separately from the navigation views allowing navigation to be started and stopped independently. + + +#### Starting Navigation +To start navigation, set a destination and start guidance: + +```tsx +try { + const waypoint = { + title: 'Destination', + position: { + lat: 37.4220679, + lng: -122.0859545, + }, + }; + + const routingOptions = { + travelMode: TravelMode.DRIVING, + avoidFerries: false, + avoidTolls: false, + }; + + await navigationController.setDestinations([waypoint], routingOptions); + await navigationController.startGuidance(); +} catch (error) { + console.error('Error starting navigation', error); +} + +``` + + +#### Adding navigation listeners + +```tsx +const { navigationController, addListeners, removeListeners } = useNavigation(); + +const onArrival = useCallback((event: ArrivalEvent) => { + if (event.isFinalDestination) { + console.log('Final destination reached'); + navigationController.stopGuidance(); + } else { + console.log('Continuing to the next destination'); + navigationController.continueToNextDestination(); + navigationController.startGuidance(); + } +}, [navigationController]); + +const navigationCallbacks = useMemo(() => ({ + onArrival, + // Add other callbacks here +}), [onArrival]); + +useEffect(() => { + addListeners(navigationCallbacks); + return () => { + removeListeners(navigationCallbacks); + }; +}, [navigationCallbacks, addListeners, removeListeners]); +``` + +See `NavigationCallbacks` interface for a list of available callbacks. + +When removing listeners, ensure you pass the same object that was used when adding them, as multiple listeners can be registered for the same event. + ### Add a navigation view You can now add a `NavigationView` component to your application.. @@ -83,24 +207,24 @@ The `NavigationView` compoonent should be used within a View with a bounded size in an unbounded widget will cause the application to behave unexpectedly. ```tsx - // Permissions must have been granted by this point. - - +// Permissions must have been granted by this point. + + ``` ### Add a map view @@ -114,8 +238,6 @@ You can also add a bare `MapView` that works as a normal map view without naviga /> ``` -See the [example](./example) directory for a complete navigation sample app. - ### Requesting and handling permissions The Google Navigation SDK React Native library offers functionalities that necessitate specific permissions from the mobile operating system. These include, but are not limited to, location services, background execution, and receiving background location updates. @@ -159,6 +281,10 @@ By default, `NavigationView` uses all the available space provided to it. To adj /> ``` +### Sample application + +See the [example](./example) directory for a complete navigation sample app. + ## Support for Android Auto and Apple CarPlay This plugin is compatible with both Android Auto and Apple CarPlay infotainment systems. For more details, please refer to the respective platform documentation: diff --git a/example/src/App.tsx b/example/src/App.tsx index b9afe05..aace977 100644 --- a/example/src/App.tsx +++ b/example/src/App.tsx @@ -14,7 +14,7 @@ * limitations under the License. */ -import * as React from 'react'; +import React from 'react'; import { NavigationContainer, useIsFocused, @@ -68,7 +68,7 @@ const Stack = createStackNavigator(); /** * Root component of the application. - * @return {NavigationContainer} The NavigationContainer as a root component. + * @return {NavigationProvider} The NavigationProvider as a root component. */ export default function App() { return ( diff --git a/example/src/controls/navigationControls.tsx b/example/src/controls/navigationControls.tsx index 012c970..eac1288 100644 --- a/example/src/controls/navigationControls.tsx +++ b/example/src/controls/navigationControls.tsx @@ -127,7 +127,7 @@ const NavigationControls: React.FC = ({ placeId: 'ChIJkXCsHWSAhYARsGBBQYcj-V0', // 1 Market st, SF }; - const map = [wp1, wp2]; + const waypoints = [wp1, wp2]; const routingOptions: RoutingOptions = { travelMode: TravelMode.DRIVING, @@ -135,7 +135,7 @@ const NavigationControls: React.FC = ({ avoidTolls: false, }; - navigationController.setDestinations(map, routingOptions); + navigationController.setDestinations(waypoints, routingOptions); }; const setFollowingPerspective = (index: CameraPerspective) => {