Home

Awesome

Launch Navigator Cordova/Phonegap Plugin Latest Stable Version Total Downloads

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.

<p align="center"> <img src="http://i.imgur.com/v96FhpZ.gif" /> <span>&nbsp;</span> <img src="http://i.imgur.com/mUg9WqO.gif" /> </p> <!-- DONATE -->

donate

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.

<!-- END DONATE --> <!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

Table of Contents

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

General concepts

App detection, selection and launching

Geocoding and input format of start/destination locations

Remember user's choice of navigation app

Supported navigation apps

The plugin currently supports launching the following navigation apps:

Android

iOS

Windows

Adding support for more apps

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.

Installing

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).

Using the CLI

$ 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.

PhoneGap Build

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

OKHTTP Library

Usage examples

Simple usage

Navigate to a destination address from current location.

User is prompted to choose from available installed navigation apps.

launchnavigator.navigate("London, UK");

Navigate to a destination with specified start location

launchnavigator.navigate("London, UK", {
    start: "Manchester, UK"
});

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"
});

Advanced usage

Navigate using a specific app

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
    });
});

List all of the apps supported by the current platform

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");
});

List apps available on the current device

launchnavigator.availableApps(function(results){
    for(var app in results){
        console.log(launchnavigator.getAppDisplayName(app) + (results[app] ? " is" : " isn't") +" available");
    }
});

Reporting issues

IMPORTANT: Please read the following carefully. Failure to follow the issue template guidelines below will result in the issue being immediately closed.

Reporting a bug or problem

Before opening a bug issue, please do the following:

Requesting a new feature

Before opening a feature request issue, please do the following:

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.

PlatformAppDestDest nameStartStart nameTransport modeFree
AndroidGoogle Maps (Map mode)XXX
AndroidGoogle Maps (Turn-by-turn mode)XXX
AndroidWazeXX
AndroidCityMapperXXXXX
AndroidUberXXXXX
AndroidYandexXXX
AndroidSygicXXX
AndroidHERE MapsXXXXX
AndroidMoovitXXXXX
AndroidLyftXXX
AndroidMAPS.MEXXXX
AndroidGeo: URI schemeXXN/A
AndroidCabifyXXXXX
AndroidBaidu MapsXX<sup>[1]</sup>XX<sup>[1]</sup>XX
Android99 TaxiXXXXX
AndroidGaode MapsXXXXXX
iOSApple Maps - URI schemeXXXX
iOSApple Maps - MapKit classXXXXXX
iOSGoogle MapsXXXX
iOSWazeXX
iOSCitymapperXXXXX
iOSNavigonXX
iOSTransit AppXXX
iOSYandexXXX
iOSUberXXXX
iOSTomtomXX
iOSSygicXXX
iOSHERE MapsXXXXX
iOSMoovitXXXXX
iOSLyftXXX
iOSMAPS.MEXXXX
iOSCabifyXXXXX
iOSBaidu MapsXX<sup>[1]</sup>XX<sup>[1]</sup>XX
iOS99 TaxiXXXXX
iOSGaode MapsXXXXXX
WindowsBing MapsXXXXXX

<a name="baidu_maps_nicknames">[1]</a>: 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.

PlatformAppDrivingWalkingBicyclingTransit
AndroidGoogle Maps (Turn-by-turn mode)XXXX
AndroidSygicXX
AndroidMAPS.MEXXXX
AndroidBaidu MapsXXXX
AndroidGaode MapsXXXX
iOSApple MapsXX
iOSGoogle MapsXXXX
iOSSygicXX
iOSMAPS.MEXXXX
iOSBaidu MapsXXXX
iOSGaode MapsXXXX
WindowsBing MapsXXX

Plugin API

All of the following constants and functions should be referenced from the global launchnavigator namespace. For example:

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

Android only: launch modes supported by Google Maps on Android

API methods

navigate()

The 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);

Parameters

enableDebug()

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

launchnavigator.enableDebug(true, success, error);

Parameters

isAppAvailable()

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);

Parameters

availableApps()

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);

Parameters

getAppDisplayName()

Returns the display name of the specified app.

let displayName = launchnavigator.getAppDisplayName(app);

Parameters

getAppsForPlatform()

Returns list of supported apps on a given platform.

let apps = launchnavigator.getAppsForPlatform(platform);

Parameters

supportsTransportMode()

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

let transportModeIsSupported = launchnavigator.supportsTransportMode(app, platform, launchMode);

Parameters

getTransportModes()

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

let modes = launchnavigator.getTransportModes(app, platform, launchMode);

Parameters

supportsDestName()

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

let destNameIsSupported = launchnavigator.supportsDestName(app, platform, launchMode);

Parameters

supportsStart()

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

let startIsSupported =  launchnavigator.supportsStart(app, platform, launchMode);

Parameters

supportsStartName()

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

let startNameIsSupported = launchnavigator.supportsStartName(app, platform);

Parameters

supportsLaunchMode()

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

Parameters

appSelection.userChoice.exists()

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"));
});

Parameters

appSelection.userChoice.get()

Returns current user choice of preferred navigator app.

launchnavigator.appSelection.userChoice.get(function(app){
    console.log("User preferred app is: " + launchnavigator.getAppDisplayName(app));
});

Parameters

appSelection.userChoice.set()

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");
});

Parameters

appSelection.userChoice.clear()

Clears the current user choice of preferred navigator app.

launchnavigator.appSelection.userChoice.clear(function(){
    console.log("User preferred app is cleared");
});

Parameters

appSelection.userPrompted.get()

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");
});

Parameters

appSelection.userPrompted.set()

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");
});

Parameters

appSelection.userPrompted.clear()

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");
});

Parameters

setApiKey()

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);

Parameters

Example projects

There are several example projects in the example repo which illustrate usage of this plugin:

Platform-specifics

Android

Windows

iOS

"Removing" Apple Maps

Apple Maps launch method

This plugin supports 2 different launch methods for launching the Apple Maps app on iOS.

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()

Credits

Thanks to:

License

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.