Cordova/Phonegap plugin for launching today's most popular navigation/ride apps to navigate to a destination.
Platforms: Android, iOS and Windows.
Key features:
Launch Navigator is also available as a React Native module.
I dedicate a considerable amount of my free time to developing and maintaining this Cordova plugin, along with my other Open Source software. To help ensure this plugin 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 plugin 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
navigate()
is passed a location type which the selected app doesn't support, the error callback will be invoked if:
enableGeocoding: false
in the options objectappSelection
section of options for the navigate()
function for more details.The plugin currently supports launching the following navigation apps:
Android
Any installed app that supports the geo:
URI scheme
iOS
Windows
This plugin 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.
The plugin is registered on npm as uk.co.workingedge.phonegap.plugin.launchnavigator
IMPORTANT: Note that the plugin will NOT work in a browser-emulated Cordova environment, for example by running cordova serve
or using the Ripple emulator.
This plugin is intended to launch native navigation apps and therefore will only work on native mobile platforms (i.e. Android/iOS/Windows).
$ cordova plugin add uk.co.workingedge.phonegap.plugin.launchnavigator --variable GOOGLE_API_KEY_FOR_ANDROID="{your_api_key}"
$ phonegap plugin add uk.co.workingedge.phonegap.plugin.launchnavigator --variable GOOGLE_API_KEY_FOR_ANDROID="{your_api_key}"
$ ionic cordova plugin add uk.co.workingedge.phonegap.plugin.launchnavigator --variable GOOGLE_API_KEY_FOR_ANDROID="{your_api_key}"
Note: GOOGLE_API_KEY_FOR_ANDROID=""
is safe to use if navigation is only being performed with latitude/longitude coordinates.
Add the following xml to your config.xml to use the latest version of this plugin from npm:
<plugin name="uk.co.workingedge.phonegap.plugin.launchnavigator" source="npm" >
<variable name="GOOGLE_API_KEY_FOR_ANDROID" value="{your_api_key}" />
</plugin>
GOOGLE_API_KEY_FOR_ANDROID
plugin variable during plugin installation
AndroidManifest.xml
in cleartext so carries the possible security risk of a malicious party decompiling your app to obtain your API key (see #249)OKHTTP_VERSION
plugin variable during plugin installation:
cordova plugin add uk.co.workingedge.phonegap.plugin.launchnavigator --variable GOOGLE_API_KEY_FOR_ANDROID="{your_api_key}" --variable OKHTTP_VERSION=1.2.3
User is prompted to choose from available installed navigation apps.
launchnavigator.navigate("London, UK");
launchnavigator.navigate("London, UK", {
start: "Manchester, UK"
});
Coordinates can be specified as a string or array
launchnavigator.navigate([50.279306, -5.163158], {
start: "50.342847, -4.749904"
});
launchnavigator.isAppAvailable(launchnavigator.APP.GOOGLE_MAPS, function(isAvailable){
var app;
if(isAvailable){
app = launchnavigator.APP.GOOGLE_MAPS;
}else{
console.warn("Google Maps not available - falling back to user selection");
app = launchnavigator.APP.USER_SELECT;
}
launchnavigator.navigate("London, UK", {
app: app
});
});
var platform = device.platform.toLowerCase();
if(platform == "android"){
platform = launchnavigator.PLATFORM.ANDROID;
}else if(platform == "ios"){
platform = launchnavigator.PLATFORM.IOS;
}else if(platform.match(/win/)){
platform = launchnavigator.PLATFORM.WINDOWS;
}
launchnavigator.getAppsForPlatform(platform).forEach(function(app){
console.log(launchnavigator.getAppDisplayName(app) + " is supported");
});
launchnavigator.availableApps(function(results){
for(var app in results){
console.log(launchnavigator.getAppDisplayName(app) + (results[app] ? " is" : " isn't") +" available");
}
});
IMPORTANT: Please read the following carefully. Failure to follow the issue template guidelines below will result in the issue being immediately closed.
Before opening a bug issue, please do the following:
--verbose
flag to CLI build commandscordova build ios --verbose
Before opening a feature request issue, please do the following:
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 |
Windows | Bing 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:
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 |
Windows | Bing Maps | X | X | X |
All of the following constants and functions should be referenced from the global launchnavigator
namespace. For example:
launchnavigator.PLATFORM.ANDROID
Supported platforms:
launchnavigator.PLATFORM.ANDROID
launchnavigator.PLATFORM.IOS
launchnavigator.PLATFORM.WINDOWS
Supported apps:
launchnavigator.APP.USER_SELECT
(Android & iOS) - invokes native UI for user to select available navigation applaunchnavigator.APP.GEO
(Android) - invokes a native chooser, allowing users to select an app which supports the geo:
URI scheme for navigationlaunchnavigator.APP.GOOGLE_MAPS
(Android & iOS)launchnavigator.APP.WAZE
(Android & iOS)launchnavigator.APP.CITYMAPPER
(Android & iOS)launchnavigator.APP.UBER
(Android & iOS)launchnavigator.APP.APPLE_MAPS
(iOS)launchnavigator.APP.NAVIGON
(iOS)launchnavigator.APP.TRANSIT_APP
(iOS)launchnavigator.APP.YANDEX
(Android & iOS)launchnavigator.APP.TOMTOM
(iOS)launchnavigator.APP.BING_MAPS
(Windows)launchnavigator.APP.SYGIC
(Android & iOS)launchnavigator.APP.HERE_MAPS
(Android & iOS)launchnavigator.APP.MOOVIT
(Android & iOS)launchnavigator.APP.LYFT
(Android & iOS)launchnavigator.APP.MAPS_ME
(Android & iOS)launchnavigator.APP.CABIFY
(Android & iOS)launchnavigator.APP.BAIDU
(Android & iOS)launchnavigator.APP.TAXIS_99
(Android & iOS)launchnavigator.APP.GAODE
(Android & iOS)Display names for supported apps, referenced by launchnavigator.APP
.
e.g. launchnavigator.APP_NAMES[launchnavigator.APP.GOOGLE_MAPS] == "Google Maps"
x
Transport modes for navigation:
launchnavigator.TRANSPORT_MODE.DRIVING
launchnavigator.TRANSPORT_MODE.WALKING
launchnavigator.TRANSPORT_MODE.BICYCLING
launchnavigator.TRANSPORT_MODE.TRANSIT
Android only: launch modes supported by Google Maps on Android
launchnavigator.LAUNCH_MODE.MAPS
- Maps viewlaunchnavigator.LAUNCH_MODE.TURN_BY_TURN
- Navigation viewlaunchnavigator.LAUNCH_MODE.GEO
- Navigation view via geo:
URI schemeThe plugin's primary API method. Launches a navigation app with a specified destination. Also takes optional parameters.
launchnavigator.navigate(destination, options);
OR
launchnavigator.navigate(destination, successCallback, errorCallback, options);
launchnavigator.APP
constants. e.g. launchnavigator.APP.GOOGLE_MAPS
.
If not specified, defaults to user selection via native picker UI.launchnavigator.TRANSPORT_MODE
constants.{"t": "k"}
google_maps://?t=k&...
launchnavigator.LAUNCH_MODE.MAPS
or launchnavigator.LAUNCH_MODE.TURN_BY_TURN
launchnavigator.LAUNCH_MODE.MAPS
if not specified.launchnavigator.LAUNCH_MODE.URI_SCHEME
or launchnavigator.LAUNCH_MODE.MAPKIT
launchnavigator.LAUNCH_MODE.URI_SCHEME
if not specified.app
is not specified.
launchnavigator.APP
constants, which should be displayed in the picker if the app is available.
This can be used to restrict which apps are displayed, even if they are installed. By default, all available apps will be displayed.launchnavigator.APP
constant.actionsheet.ANDROID_THEMES
constants. Default actionsheet.ANDROID_THEMES.THEME_HOLO_LIGHT
"prompt"
- Prompt user to decide whether to remember choice.
promptFn
is defined, this will be used for user confirmation.false
- Do not remember user choice.true
- Remember user choice.Enables debug log output from the plugin to the JS and native consoles. By default debug is disabled.
launchnavigator.enableDebug(true, success, error);
Determines if the given app is installed and available on the current device.
launchnavigator.isAppAvailable(appName, function(isAvailable){
console.log(appName + " is available: " + isAvaialble);
}, error);
ln.APP
.Returns a list indicating which apps are installed and available on the current device.
launchnavigator.availableApps(function(apps){
apps.forEach(function(app){
console.log(app + " is available");
});
}, error);
Returns the display name of the specified app.
let displayName = launchnavigator.getAppDisplayName(app);
launchnavigator.APP
. e.g. launchnavigator.APP.GOOGLE_MAPS
. whether the app is available.Returns list of supported apps on a given platform.
let apps = launchnavigator.getAppsForPlatform(platform);
launchnavigator.PLATFORM
. e.g. launchnavigator.PLATFORM.IOS
.launchnavigator.APP
constants.Indicates if an app on a given platform supports specification of transport mode.
let transportModeIsSupported = launchnavigator.supportsTransportMode(app, platform, launchMode);
launchnavigator.APP
. e.g. launchnavigator.APP.GOOGLE_MAPS
.launchnavigator.PLATFORM
. e.g. launchnavigator.PLATFORM.IOS
.launchnavigator.LAUNCH_MODE
. e.g. launchnavigator.LAUNCH_MODE.MAPS
.Returns the list of transport modes supported by an app on a given platform.
let modes = launchnavigator.getTransportModes(app, platform, launchMode);
launchnavigator.APP
. e.g. launchnavigator.APP.GOOGLE_MAPS
.launchnavigator.PLATFORM
. e.g. launchnavigator.PLATFORM.IOS
.launchnavigator.LAUNCH_MODE
. e.g. launchnavigator.LAUNCH_MODE.MAPS
.launchnavigator.TRANSPORT_MODE
.
If app/platform combination doesn't support specification of transport mode, the list will be empty;Indicates if an app on a given platform supports specification of a custom nickname for destination location.
let destNameIsSupported = launchnavigator.supportsDestName(app, platform, launchMode);
launchnavigator.APP
. e.g. launchnavigator.APP.GOOGLE_MAPS
.launchnavigator.PLATFORM
. e.g. launchnavigator.PLATFORM.IOS
.launchnavigator.LAUNCH_MODE
. e.g. launchnavigator.LAUNCH_MODE.MAPS
.Indicates if an app on a given platform supports specification of start location.
let startIsSupported = launchnavigator.supportsStart(app, platform, launchMode);
launchnavigator.APP
. e.g. launchnavigator.APP.GOOGLE_MAPS
.launchnavigator.PLATFORM
. e.g. launchnavigator.PLATFORM.IOS
.launchnavigator.LAUNCH_MODE
. e.g. launchnavigator.LAUNCH_MODE.MAPS
.Indicates if an app on a given platform supports specification of a custom nickname for start location.
let startNameIsSupported = launchnavigator.supportsStartName(app, platform);
launchnavigator.APP
. e.g. launchnavigator.APP.GOOGLE_MAPS
.launchnavigator.PLATFORM
. e.g. launchnavigator.PLATFORM.IOS
.launchnavigator.LAUNCH_MODE
. e.g. launchnavigator.LAUNCH_MODE.MAPKIT
.Indicates if an app on a given platform supports specification of launch mode.
Currently only Google Maps on Android and Apple Maps on iOS does.
let launchModeIsSupported = launchnavigator.supportsLaunchMode(app, platform);
launchnavigator.APP
. e.g. launchnavigator.APP.GOOGLE_MAPS
.launchnavigator.PLATFORM
. e.g. launchnavigator.PLATFORM.ANDROID
.Indicates whether a user choice exists for a preferred navigator app.
launchnavigator.appSelection.userChoice.exists(function(exists){
console.log("User preference of app: " + (exists ? "exists" : "doesn't exist"));
});
Returns current user choice of preferred navigator app.
launchnavigator.appSelection.userChoice.get(function(app){
console.log("User preferred app is: " + launchnavigator.getAppDisplayName(app));
});
launchnavigator.APP
.Sets the current user choice of preferred navigator app.
launchnavigator.appSelection.userChoice.set(launchnavigator.APP.GOOGLE_MAPS, function(){
console.log("User preferred app is set");
});
launchnavigator.APP
.Clears the current user choice of preferred navigator app.
launchnavigator.appSelection.userChoice.clear(function(){
console.log("User preferred app is cleared");
});
Indicates whether user has already been prompted whether to remember their choice a preferred navigator app.
launchnavigator.appSelection.userPrompted.get(function(alreadyPrompted){
console.log("User " + (alreadyPrompted ? "has" : "hasn't") + " already been asked whether to remember their choice of navigator app");
});
Sets flag indicating user has already been prompted whether to remember their choice a preferred navigator app.
launchnavigator.appSelection.userPrompted.set(function(){
console.log("Flag set to indicate user chose to remember their choice of navigator app");
});
Clears flag which indicates if user has already been prompted whether to remember their choice a preferred navigator app.
launchnavigator.appSelection.userPrompted.clear(function(){
console.log("Clear flag indicating whether user chose to remember their choice of navigator app");
});
Sets the Google API key for Android. Note: This function is also available on iOS but it does nothing. This is to keep the interface consistent between the platforms.
launchnavigator.setApiKey(api_key, success, error);
There are several example projects in the example repo which illustrate usage of this plugin:
Running on Android, in addition to discovering which explicitly supported apps are installed, the plugin will also detect which installed apps support using the geo:
URI scheme for use in navigation. These are returned in the list of available apps.
By specifying the app
option as launchnavigator.APP.GEO
, the plugin will invoke a native Android chooser, to allow the user to select an app which supports the geo:
URI scheme for navigation.
Google Maps on Android can be launched in 3 launch modes:
launchnavigator.LAUNCH_MODE.MAPS
) - launches in Map view. Enables start location to be specified, but not transport mode or destination name.launchnavigator.LAUNCH_MODE.TURN_BY_TURN
) - launches in Navigation view. Enables transport mode to be specified, but not start location or destination name.launchnavigator.LAUNCH_MODE.GEO
) - invokes Navigation view via geo
: URI scheme. Enables destination name to be specified, but not start location or transport mode.launchModeGoogleMaps
option, but defaults to Maps mode if not specified.The plugin is compatible with Windows 10 on any PC or Windows 10 Mobile on a phone/tablet using the Universal .Net project generated by Cordova: cordova platform add windows
Bing Maps requires the user to press the enter key to initiate navigation if you don't provide the start location.
Therefore, if a start location is not going to be passed to the plugin from your app, you should install the Geolocation plugin into your project.
By default, if the geolocation plugin is detected, the plugin will attempt to retrieve the current device location using it, and use this as the start location.
This can be disabled via the enableGeolocation
option.
launchnavigator.availableApps()
will always report it as present.launchnavigator.navigate()
This plugin supports 2 different launch methods for launching the Apple Maps app on iOS.
launchModeAppleMaps
option as a launchnavigator.LAUNCH_MODE
constant to navigate()
launchnavigator.LAUNCH_MODE.URI_SCHEME
: use the URI scheme launch method. Default if not specified.launchnavigator.LAUNCH_MODE.MAPKIT
: use the MapKit class launch method.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.
On both Android and iOS, the extra parameters client_id
and deep_link_product_id
are required by 99 Taxi
client_id
should follow the pattern MAP_***
where ***
is the client name given by the 99 Team.
client_id=MAP_123
deep_link_product_id
identifies the ride category
316
- POP ride326
- TOP ride327
- Taxis ridedeep_link_product_id=316
On Android, 99 Taxi is currently the only app where options.start
is a required parameter when calling navigate()
navigate()
is called without a start location and the selected app is 99 Taxi, the error callback will be invoked and the 99 Taxi app will not be launchedAndroidManifest.xml
cordova-plugin-geolocation
to find this.Thanks to:
The MIT License
Copyright (c) 2016 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.