@mendix/uk.co.workingedge.phonegap.plugin.launchnavigator
Advanced tools
Cordova/Phonegap plugin to navigate to a destination using native navigation apps on Android, iOS, and Windows Phone
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 find 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
$ phonegap plugin add uk.co.workingedge.phonegap.plugin.launchnavigator
$ ionic cordova plugin add uk.co.workingedge.phonegap.plugin.launchnavigator
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" />
OKHTTP_VERSION plugin variable during plugin installation:
cordova plugin add uk.co.workingedge.phonegap.plugin.launchnavigator --variable OKHTTP_VERSION=1.2.3User 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");
}
});
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.ANDROIDlaunchnavigator.PLATFORM.IOSlaunchnavigator.PLATFORM.WINDOWSSupported 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.DRIVINGlaunchnavigator.TRANSPORT_MODE.WALKINGlaunchnavigator.TRANSPORT_MODE.BICYCLINGlaunchnavigator.TRANSPORT_MODE.TRANSITAndroid 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_TURNlaunchnavigator.LAUNCH_MODE.MAPS if not specified.launchnavigator.LAUNCH_MODE.URI_SCHEME or launchnavigator.LAUNCH_MODE.MAPKIT
- Defaults to 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.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");
});
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 8.1 or Windows 10 on any PC and on Windows Phone 8.0/8.1 using the Universal .Net project generated by Cordova: cordova platform add windows or cordova platform add wp8 (for windows phone 8.0)
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_123deep_link_product_id identifies the ride category
316 - POP ride326 - TOP ride327 - Taxis ridedeep_link_product_id=316On 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.xmlcordova-plugin-geolocation to find this.Before reporting issues with this plugin, please first do the following:
When reporting issues, please give the following information:
A clear description of the problem
OS version(s) and device (or emulator) model(s) on which the problem was observed
Code example of calling the plugin which results in the observed issue
Example parameters (locations or place names) which results in the observed issue
Issues which fail to give a clear description of the problem as described above will be closed immediately
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.
FAQs
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket Firewall Enterprise is now available with flexible deployment, configurable policies, and expanded language support.
Security News
Open source dashboard CNAPulse tracks CVE Numbering Authorities’ publishing activity, highlighting trends and transparency across the CVE ecosystem.
Product
Detect malware, unsafe data flows, and license issues in GitHub Actions with Socket’s new workflow scanning support.