search

dpa99c / react-native-launch-navigator

A React Native module for launching today's most popular navigation/ride apps to navigate to a destination.
144 stars 35 forks source link

readme

React Native Launch Navigator Latest Stable Version Total Downloads

A React Native module for launching today's most popular navigation/ride apps to navigate to a destination.

Platforms: Android and iOS.

Key features:

 

Launch Navigator functionality is also available as a Cordova/Phonegap plugin.

donate

I dedicate a considerable amount of my free time to developing and maintaining my Open Source software. To help ensure this module is kept updated, new features are added and bugfixes are implemented quickly, please donate a couple of dollars (or a little more if you can stretch) as this will help me to afford to dedicate time to its maintenance. Please consider donating if you're using this software in an app that makes you money, if you're being paid to make the app, if you're asking for new features or priority bug fixes.

Table of Contents

General concepts

App detection, selection and launching

Geocoding and input format of start/destination locations

Supported navigation apps

The module currently supports launching the following navigation apps:

Android

iOS

Adding support for more apps

This module is a work in progress. I'd like it to support launching of as many popular navigation apps as possible.

If there's another navigation app which you think should be explicitly supported and it provides a mechanism to externally launch it, open an issue containing a link or details of how the app should be invoked.

Don't just open an issue saying "Add support for Blah" without first finding out if/how it can be externally launched. I don't have time to research launch mechanisms for every suggested app, so I will close such issues immediately.

Installation

npm install --save react-native-launch-navigator

For iOS only:

cd ios && pod install

Add iOS URL schemes

On iOS, for each installed navigation app you want your app to be able to launch, you must manually whitelist its custom URL scheme in your app's Info.plist. Note: this is required since React Native v0.60 added autolinking and removed support for postlink hook scripts which made it possible to automate this step.

Add the URL schemes for the navigation apps you want to support to the LSApplicationQueriesSchemes key in your Info.plist:

App Scheme
City Mapper citymapper
Google Maps comgooglemaps
Garmin Navigon navigon
Transit App transit
Waze waze
Yandex Navigator yandexnavi
Uber uber
Tomtom tomtomhome
Sygic com.sygic.aura
HERE Maps here-route
Moovit moovit
Lyft lyft
MAPS.ME mapsme
Cabify cabify
Baidu Maps baidumap
99 Taxi taxis99
Gadode iosamap

The full list of URL schemes above can be found in the example project's Info.plist.

Usage

Import the module into your app:

import LaunchNavigator from 'react-native-launch-navigator';

Simple usage

On Android, don't forget to set your Google API key:

if(Platform.OS === "android") LaunchNavigator.setGoogleApiKey("your_api_key");

Navigate to a destination address from current location.

Uses default OS navigation app (Google Maps on Android / Apple Maps on iOS).

LaunchNavigator.navigate("London, UK")
    .then(() => console.log("Launched navigator"))
    .catch((err) => console.error("Error launching navigator: "+err));

Navigate to a destination with specified start location

LaunchNavigator.navigate("London, UK", {
    start: "Manchester, UK"
})
    .then(() => console.log("Launched navigator"))
    .catch((err) => console.error("Error launching navigator: "+err));

Navigate using latitude/longitude coordinates

Coordinates can be specified as a string or array

LaunchNavigator.navigate([50.279306, -5.163158], {
    start: "50.342847, -4.749904"
})
    .then(() => console.log("Launched navigator"))
    .catch((err) => console.error("Error launching navigator: "+err));

Advanced usage

Navigate using a specific app

let app = null;

LaunchNavigator.isAppAvailable(LaunchNavigator.APP.WAZE).then((isWazeAvailable) => {
    if(isWazeAvailable){
        app = LaunchNavigator.APP.WAZE;
    }else{
        console.warn("Waze not available - falling back to default navigation app");
    }

    LaunchNavigator.navigate("London, UK", {
        app: app
    });
        .then(() => console.log("Launched navigator"))
        .catch((err) => console.error("Error launching navigator: "+err));
});

List all of the apps supported by the current platform

if(Platform.OS === "android"){
    platform = LaunchNavigator.PLATFORM.ANDROID;
}else if(Platform.OS == "ios"){
    platform = LaunchNavigator.PLATFORM.IOS;
}

LaunchNavigator.getAppsForPlatform(platform).forEach((app) => {
    console.log(LaunchNavigator.getAppDisplayName(app) + " is supported");
});

List apps available on the current device

let apps = LaunchNavigator.getAvailableApps();
for(let app in apps){
    console.log(LaunchNavigator.getAppDisplayName(app) + (apps[app] ? " is" : " isn't") +" available");
}

Supported parameters

Different apps support different input parameters on different platforms. Any input parameters not supported by a specified app will be ignored.

The following table enumerates which apps support which parameters.

Platform App Dest Dest name Start Start name Transport mode Free
Android Google Maps (Map mode) X X X
Android Google Maps (Turn-by-turn mode) X X X
Android Waze X X
Android CityMapper X X X X X
Android Uber X X X X X
Android Yandex X X X
Android Sygic X X X
Android HERE Maps X X X X X
Android Moovit X X X X X
Android Lyft X X X
Android MAPS.ME X X X X
Android Geo: URI scheme X X N/A
Android Cabify X X X X X
Android Baidu Maps X X[1] X X[1] X X
Android 99 Taxi X X X X X
Android Gaode Maps X X X X X X
iOS Apple Maps - URI scheme X X X X
iOS Apple Maps - MapKit class X X X X X X
iOS Google Maps X X X X
iOS Waze X X
iOS Citymapper X X X X X
iOS Navigon X X
iOS Transit App X X X
iOS Yandex X X X
iOS Uber X X X X
iOS Tomtom X X
iOS Sygic X X X
iOS HERE Maps X X X X X
iOS Moovit X X X X X
iOS Lyft X X X
iOS MAPS.ME X X X X
iOS Cabify X X X X X
iOS Baidu Maps X X[1] X X[1] X X
iOS 99 Taxi X X X X X
iOS Gaode Maps X X X X X X

[1]: Only supported when Start or Dest is specified as lat/lon (e.g. "50,-4")

Table columns:

Transport modes

Apps that support specifying transport mode.

Platform App Driving Walking Bicycling Transit
Android Google Maps (Turn-by-turn mode) X X X X
Android Sygic X X
Android MAPS.ME X X X X
Android Baidu Maps X X X X
Android Gaode Maps X X X X
iOS Apple Maps X X
iOS Google Maps X X X X
iOS Sygic X X
iOS MAPS.ME X X X X
iOS Baidu Maps X X X X
iOS Gaode Maps X X X X

Module API

All of the module constants and functions should be referenced from the namespace used to import the module, for example:

import LaunchNavigator from 'react-native-launch-navigator';
let android = LaunchNavigator.PLATFORM.ANDROID;

Constants

PLATFORM

Supported platforms:

APP

Supported apps:

APP_NAMES

Display names for supported apps, referenced by LaunchNavigator.APP.

e.g. LaunchNavigator.APP_NAMES[LaunchNavigator.APP.GOOGLE_MAPS] == "Google Maps" x

TRANSPORT_MODE

Transport modes for navigation:

LAUNCH_MODE

Launch modes supported by Google Maps on Android (see Google Maps launch modes):

Launch modes supported by Apple Maps on iOS (see Apple Maps launch modes:

API methods

navigate()

Launches a navigation app with a specified destination.

LaunchNavigator.navigate(destination, options);

Parameters

Returns

isAppAvailable()

Determines if the given app is installed and available on the current device.

let app = LaunchNavigator.APP.WAZE;
LaunchNavigator.isAppAvailable(app)
    .then((isAvailable) => {
        console.log(LaunchNavigator.getAppDisplayName(app)+" is available: "+isAvailable);
    })
    .catch((error) => {
        console.error(error);
    });

Parameters

Returns

getAvailableApps()

Returns a list indicating which apps are installed and available on the current device for the current platform.

LaunchNavigator.getAvailableApps()
    .then((apps) => {
        for(let app in apps){
            console.log(LaunchNavigator.getAppDisplayName(app)+" is "+(apps[app] ? "available" : "unavailable"));
        }
    })
    .catch((error) => {
        console.error(error);
    });

Returns

getAppDisplayName()

Returns the display name of the specified app.

let name = LaunchNavigator.getAppDisplayName(LaunchNavigator.APP.WAZE);

Parameters

Returns

getAppsForPlatform()

Returns list of supported apps on a given platform.

let apps = LaunchNavigator.getAppsForPlatform(platform);

Parameters

Returns

supportsTransportMode()

Indicates if an app on a given platform supports specification of transport mode.

let isSupported = LaunchNavigator.supportsTransportMode(app, platform, launchMode);

Parameters

Returns

getTransportModes()

Returns the list of transport modes supported by an app on a given platform.

let transportModes = LaunchNavigator.getTransportModes(app, platform, launchMode);

Parameters

Returns

supportsDestName()

Indicates if an app on a given platform supports specification of a custom nickname for destination location.

let isSupported = LaunchNavigator.supportsDestName(app, platform, launchMode);

Parameters

Returns

supportsStart()

Indicates if an app on a given platform supports specification of start location.

let isSupported = LaunchNavigator.supportsStart(app, platform, launchMode);

Parameters

Returns

supportsStartName()

Indicates if an app on a given platform supports specification of a custom nickname for start location.

let isSupported = LaunchNavigator.supportsStartName(app, platform, launchMode);

Parameters

Returns

supportsLaunchMode()

Indicates if an app on a given platform supports specification of launch mode.

Parameters

Returns

enableDebug()

Enables debug log output from the module to the JS and native consoles. By default debug is disabled.

LaunchNavigator.enableDebug(true);

Parameters

setGoogleApiKey()

Enables specification of the Google API key to use for accessing Google's Geocoding API. If you fail to set this on Android before attempting to use this module to launch a navigation app which requires a lat/lon coordinates as input, the module will raise an error if the input location is an address because it requires geocoding to a lat/lon coordinate. See Google API key for Android for more information.

Android only. Calling on iOS will have no effect.

LaunchNavigator.setGoogleApiKey("your_api_key");

Parameters

Example project

The example project can be used to build and run a React Native app for Android & iOS:

https://github.com/dpa99c/react-native-launch-navigator-example

It demonstrates how this module can be used and validates its functionality.

Platform-specifics

Android

Google API key for Android

geo: URI scheme

Google Maps launch modes

Google Maps on Android can be launched using 3 launch modes by specifying the launchMode option as a LaunchNavigator.LAUNCH_MODE constant to navigate():

iOS

"Removing" Apple Maps

Apple Maps launch modes

Apple Maps app on iOS can be launched using 2 launch methods by specifying the launchMode option as a LaunchNavigator.LAUNCH_MODE constant to navigate():

URI scheme launch method

MapKit class launch method

App-specifics

Lyft

On both Android and iOS, the "ride type" will default to "Lyft" unless otherwise specified in the extras list as id.

See the Lyft documentation for URL scheme details and other supported ride types.

99 Taxi

On both Android and iOS, the extra parameters client_id and deep_link_product_id are required by 99 Taxi

On Android, 99 Taxi is currently the only app where options.start is a required parameter when calling navigate()

Reporting issues

Before reporting issues with this module, please first do the following:

When reporting issues, please give the following information:

Issues which fail to give a clear description of the problem as described above will be closed immediately

License

The MIT License

Copyright (c) 2018 Dave Alden (Working Edge Ltd.)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.