A class containing static methods for setting and checking various CoPilot features and settings.
Supported on Android Since Version
9.6.0.821
Supported on iOS Since Version
10.9
Type
Class
Package
com.alk.cpik
Methods
Method Name
Return Type
Description
enableMotionLock(boolean) Deprecated, use setMotionLockMode.
void
Enables or disables Motion Lock, which locks the navigation map when the vehicle is in motion.
getMotionLockEnabled() Deprecated, use getMotionLockMode
Boolean
Returns whether Motion Lock is enabled or disabled.
setMotionLockMode(MotionLockMode)
void
Motion lock will lock the CoPilot UI once traveling above a specified speed. The UI can be locked down over a different range of modes, restricting more or less of the UI based on integration needs.
Returns a CopilotVersion object containing information about CoPilot’s application version number and map data version.
setTurnInstructionCallbackDelay(int)
void
Sets the time between when turn instruction callbacks onReadyToSpeakTurnInstruction and onSpeakTurnInstructionComplete are fired when CoPilot starts speaking.
getTurnInstructionCallbackDelay()
Int
Retrieves the current delay between when the turn instruction callbacks onReadyToSpeakTurnInstruction and onSpeakTurnInstructionComplete.
getView() [Android only]
View
Retrieves the view associated with the CoPilot service.
isActive() [Android only]
Boolean
Determines if CoPilot can receive API calls. APIs can only be called after the onCPStartup callback is sent and before the onCPShutdown callback returns.
enableGPS() [Android only]
void
Restarts the CoPilot GPS Service and resumes all suspended GPS activities including listening, and processing.
disableGPS() [Android only]
void
Suspends background GPS/routing processing and deregister the CoPilot GPS Service. Background Navigation will not work after this API call.
Sets the CopilotStartupParams object that contains overridden methods used during CoPilot Startup.
addFavorite(Favorite)
void
Adds a new favorite to CoPilot’s favorites list.
removeFavorite(int)
void
Removes a favorite from CoPilot.
getFavoritesList()
List<Favorite>
Returns the list of favorites currently stored in CoPilot’s favorites list.
CopilotMgr.singleSearchInit
Overview
Description
This API initiates single search. This includes several HTTP requests and requires internet connection. Once the initialization has successfully finished, a callback onSingleSearchReady will be returned indicating that the other Single Search APIs are available to use. Note: This API must be called and the onSingleSearchReady callback received before Single Search APIs can be used.
Supported Since Version
10.9
Platforms Supported
Android, Linux
Type
Method
Package
com.alk.cpik
Sample Code
CopilotMgr.singleSearchInit();// In your CopilotListener file@OverridepublicvoidonSingleSearchReady(){// Single search is ready}
SingleSearchError
Overview
Description
A response enum from a request to the Single Search web service. Responses will provide information on the result of the request including specific reasons if a request fails.
Supported Since Version
10.9
Platforms Supported
Android, Linux
Type
Enum
Package
com.alk.cpik
Values
Value
Description
OK
Successfully get the single search response
FAILURE_INIT
Failed to initialize single search
FAILURE_WEBSERVICE
Single Search Web Service returns errors
FAILURE_CONNECT
There are network connection issues
FAILURE_INVALID_JSON
While using singleSearchJSON API, the JSON parameter user passes in is invalid
FAILURE_DATA_NOT_LICENSED_OR_NOT_INSTALLED
You requested data is either not licensed or not installed
FAILURE_DATA_NOT_AVAILABLE_FOR_RESULT
The stop results returned from single search web service are not valid in CoPilot installed data
FAILURE_GENERIC
Unknown errors
CopilotMgr.singleSearch
Overview
Description
This API is used for a Single Search query. It will send user’s query string together with all default search settings to the Single Search web service. This API is not synchronous. A callback onSingleSearchFinished will be returned once web service gives the response back.
Supported Since Version
10.9
Platforms Supported
Android, Linux
Type
Method
Package
com.alk.cpik
Syntax - static void singleSearch(String query)
Parameters
String: Single search query string. Can be address, POI name, street name, city name, zip.
Sample Code
CopilotMgr.singleSearch("1 independence way princeton nj");// In your CopilotListener file@OverridepublicvoidonSingleSearchFinished(StopListstopList,SingleSearchErrorerror){if(SingleSearchError.OK==error){// Do something with stopList}else{// Do something with error}}
CopilotMgr.singleSearchJSON
Overview
Description
This API is used for Single Search query. User needs to pass a JSON string containing the query with the customized search settings. This API is not synchronous. A callback onSingleSearchFinished will be fired once web service gives the response back.
Parameters
String: A json string that contains query string as well as search settings. Below is an example:
{"Query":"1 independence way princeton nj","MaxResults":20,"Location":{"Address":{"StreetAddress":"1 independence way","City":"Princeton","State":"NJ","Zip":"08540","County":"Mercer","Country":""},"Coords":{"Lat":"40.361076","Lon":"-74.601515"}},"Searchtype":1,// Searchtype filters search results so that the API only returns certain types of matching locations.
// Possible values are: 0 - ALL (Default), 1- ADDRESS_ONLY, 2- POI_ONLY, 3- CITY_ONLY, 4- CUSTOM_PLACE_ONLY
"PoiCategories":["Airport","bank","CAT scales"],"Countries":["CA","US","GL"],"States":["NJ","NM"]
Sample Code
// Assuming you formed the json into queryJSONCopilotMgr.singleSearchJSON(queryJSON);// In your CopilotListener file@OverridepublicvoidonSingleSearchFinished(StopListstopList,SingleSearchErrorerror){if(SingleSearchError.OK==error){// Do something with stopList}else{// Do something with error}}
CopilotMgr.getSingleSearchPOICategories
Overview
Description
This API is used to get a list of POI categories that can be recognized by Single Search web service. This is used to form the json string for singleSearchJSON API, specifically the “PoiCategories” field.
Supported Since Version
10.9
Platforms Supported
Android, Linux
Type
Method
Package
com.alk.cpik
Syntax - static List getSingleSearchPOICategories()
Return Values - List
Sample Code
List<String>poiCategories=CopilotMgr.getSingleSearchPOICategories();Stringresult="";for(Stringpoi:poiCategories){// Do something with poi}
CopilotMgr.getSingleSearchCountries
Overview
Description
This API will return the list of countries the user is able to search within. User may need it to form the JSON string (the “Countries” field) for singleSearchJSON API. Please note the countries that are returned must have been licensed, map data present on the device and those countries supported by the Single Search Web service.
Supported Since Version
10.9
Platforms Supported
Android, Linux
Type
Package
com.alk.cpik
Syntax - static List getSingleSearchCountries ()
Return Values - List
Sample Code
List<String>countries=CopilotMgr.getSingleSearchCountries();Stringresult="";for(Stringcountry:countries){// Do something with country}
CopilotMgr.getSingleSearchStates
Overview
Description
This API will return the list of states the user is able to search within. User may need it to form the JSON string (the “States” field) for singleSearchJSON API. Please note the states that are returned are those within regions that have been licensed, appropriate map data is present on the device and those states supported by the Single Search Web service.
Supported Since Version
10.9
Platforms Supported
Android, Linux
Type
Method
Package
com.alk.cpik
Sample Code
List<String>states=CopilotMgr.getSingleSearchStates();Stringresult="";for(Stringstate:states){// Do something with state}
Motion Lock
Motion Lock is a safety feature within CoPilot which limits access to the CoPilot UI once traveling above a threshold speed. This feature has been enhanced to increase the amount of interaction that is available through multiple modes available.
CopilotMgr.setMotionLockMode
Overview
Description
Motion lock will lock the CoPilot UI once traveling above a specified speed. The UI can be locked down over a different range of modes, restricting more or less of the UI based on integration needs. The threshold at which Motion Lock will be initiated should be set using setMotionLockSpeedThreshold. This API is just to set the lock mode, it’s not responsible for the actual lock to be activated.
Supported Since Version
10.9
Platforms Supported
Android, Linux
Type
Method
Package
com.alk.cpik
Syntax
staticvoidsetMotionLockMode(MotionLockModemode)
Parameters
Parameter
Description
MotionLockMode
The mode that you want CoPilot to locked down to once motion lock has been initiated. This will dictate the available options once traveling above the specified threshold speed.
Sample Code
// set ALL_UI_LOCK modeCopilotMgr.setMotionLockMode(MotionLockMode.ALL_UI_LOCK);
CopilotMgr.getMotionLockMode
Overview
Description
To return the current Motion Lock mode this API should be used. The mode dictates the extent to which the CoPilot UI will be locked down once initiated and traveling above the threshold speed. This will not return the threshold speed.
A value representing the Motion Lock UI mode that CoPilot will apply when motion lock is activated.
Supported Since Version
10.9
Platforms Supported
Android, Linux
Type
Enum
Package
com.alk.cpik
Values
Value
Description
ALL_UI_UNLOCK
Unlock all UI, do not lock any UI elements when traveling above the threshold speed.
ALL_UI_LOCK
Lock all UI when traveling above the defined threshold speed. This will also disable all pop ups except for the destination arrival pop up. All action required pop-ups have a default decision which will be followed if they are shown.
ONLY_DRIVING_UI_ACCESS
Only allow access to driving functions. This will Lock access to the entire UI with the exception of the following:
Driving Menu → 2D/3D Driving menu → Directions/Safety Driving Menu → Clear Destination Driving Menu → Close Zoom buttons on map Reset to current location button on map POI Alert button on map Popups Map drag/swipe/pan/multi touch Sound mute button Mapsure button on navigation dialog
This is the default mode available within the CoPilot UI.
ONLY_DRIVING_UI_ACCESS_EXTEND
ONLY_DRIVING_UI_ACCESS plus access to the following (disable keyboard):
Driving Menu → Find POIs Main POI categories Search All More Categories Driving Menu → My Route → Alternate Go (Green circular button on plan trip screen) Traffic Bar and traffic refresh button Buttons in flow traffic map except for the setting button
PASSENGER_MODE
Allow a temporary disablement of Motion Lock when used by a passenger. Motion Lock settings should be resumed upon restarting CoPilot. When this mode is set, all UI will be unlocked. Once the application is re-launched CoPilot will resume in the previous MotionLock mode. To enable this mode the following configuration is required to be set within the user.cfg:
[User Settings] “EnablePassengerMode”=1
Once this is set this mode being passed will replicate the user selecting the passenger mode button within the UI.
CopilotMgr.getMotionLockSpeedThreshold
Overview
Description
Returns the current speed threshold at which Motion Lock will be enabled. Motion Lock will lock the CoPilot navigation screen, preventing user input, when the vehicle’s speed reaches this threshold.
try{// Get the current motion lock speed threshold and printMotionLockSpeedThresholdthreshold=CopilotMgr.getMotionLockSpeedThreshold();switch(threshold){caseLEVEL_1:System.out.println("Motion lock will enable at 5 MPH");break;caseLEVEL_2:System.out.println("Motion lock will enable at 10 MPH");break;caseLEVEL_3:System.out.println("Motion lock will enable at 15 MPH");break;caseLEVEL_4:System.out.println("Motion lock will enable at 20 MPH");break;default:System.out.println("Motion lock threshold is not set");break;}}catch(CopilotExceptione){System.out.println("Exception! : "+e.toString());}
NSString*value=[[[NSStringalloc]init]autorelease];switch([CopilotMgrgetMotionLockSpeedThreshold]){caseCP_LEVEL_NOT_SET:value=@"CP_LEVEL_NOT_SET";break;caseCP_LEVEL_1:value=@"CP_LEVEL_1";break;caseCP_LEVEL_2:value=@"CP_LEVEL_2";break;caseCP_LEVEL_3:value=@"CP_LEVEL_3";break;caseCP_LEVEL_4:value=@"CP_LEVEL_4";break;default:break;}NSLog([NSStringstringWithFormat:@"Motion Lock Speed threshold is: %@",value]);
CopilotMgr.setMotionLockSpeedThreshold
Overview
Description
Sets the threshold (in mph) for enabling and disabling Motion Lock. Motion Lock prevents user interaction with CoPilot while driving at or above a specified speed threshold. The values for this API can be found in the MotionLockSpeedThreshold Enum API.
speedThreshold – An Enum indicating the speed limit which, once reached, will enforce Motion Lock.
Sample Code
Java
try{// Set motion lock to enable at speeds over 5 MPHCopilotMgr.setMotionLockSpeedThreshold(MotionLockSpeedThreshold.LEVEL_1);// Set motion lock to enable at speeds over 15 MPHCopilotMgr.setMotionLockSpeedThreshold(MotionLockSpeedThreshold.LEVEL_3);}catch(CopilotExceptione){System.out.println("Exception! : "+e.toString());}
Returns the measurement type currently set within CoPilot, metric or imperial. Units of Measurement are used for functions including speed, distance and vehicle dimensions.
Supported on Android Since Version
9.6.0.821
Supported on Android Since Version
10.9
Type
Method
Package
com.alk.cpik
Measure
Metric
Imperial
Speed
Kilometers per Hour (KPH)
Miles per Hour (MPH)
Distance
Kilometers, Meters, Centimeters
Miles, Feet, Inches
Vehicle Dimensions
Meters, Centimeters, Ton
Feet, Inches, Ton, 000’s Pounds (US)
Syntax
UnitsOfMeasuregetUnitsOfMeasure()
+(CP_UnitsOfMeasure)getUnitsOfMeasure
Return Value
UnitsOfMeasure - An Enum representing either metric or imperial units.
Sample Code
try{// Print which measurement system CoPilot is usingUnitsOfMeasurecurrentUnits=CopilotMgr.getUnitsOfMeasure();if(currentUnits==UnitsOfMeasure.METRIC)System.out.println("CoPilot is using the metric units");elseif(currentUnits==UnitsOfMeasure.IMPERIAL)System.out.println("CoPilot is using the imperial units");}catch(CopilotExceptione){e.printStackTrace();}
NSString*isMetric;if([CopilotMgrgetUnitsOfMeasure]==CP_METRIC)isMetric=@"Units of measure: Metric";elseisMetric=@"Units of measure: Imperial";NSLog(isMetric);
CopilotMgr.setUnitsOfMeasure
Overview
Description
Sets whether metric or imperial values should be used within CoPilot. Units of Measurement are used for functions including speed, distance and vehicle dimensions.
Supported on Android Since Version
9.6.0.757
Supported on iOS Since Version
10.9
Type
Method
Package
com.alk.cpik
Measure
Metric
Imperial
Speed
Kilometers per Hour (KPH)
Miles per Hour (MPH)
Distance
Kilometers, Meters, Centimeters
Miles, Feet, Inches
Vehicle Dimensions
Meters, Centimeters, Ton
Feet, Inches, Ton, 000’s Pounds (US)
Syntax
voidsetUnitsOfMeasure(UnitsOfMeasure)
+(void)setUnitsOfMeasure(enumCP_UnitsOfMeasure)
Parameters
UnitsOfMeasure - An Enum representing either metric or imperial units.
Return Value
Void
Sample Code
try{// Set CoPilot to use the metric unit systemCopilotMgr.setUnitsOfMeasure(UnitsOfMeasure.METRIC);// Set CoPilot to use the imperial unit systemCopilotMgr.setUnitsOfMeasure(UnitsOfMeasure.IMPERIAL);}catch(CopilotExceptione){e.printStackTrace();}
Returns a CoPilot version object, which includes details of the currently installed CoPilot application version number as well as the map data release (year and quarter).
Supported on Android Since Version
9.6.0.821
Supported on Android Since Version
10.9
Type
Method
Package
com.alk.cpik
Syntax
CopilotVersionStringgetVersionInfo()
+(CoPilotVersion*)getVersionInfo
Return Value
CopilotVersion containing information about the version of the CoPilot application and map data.
Sample Code
try{// Print information about CoPilotCopilotVersioncurrVersion=CopilotMgr.getVersionInfo();System.out.println("CoPilot application version: "+currVersion.getAppVersion());System.out.println("CoPilot map data version: "+currVersion.getDataVersion());System.out.println("CoPilot map data year: "+currVersion.getDataYear());System.out.println("CoPilot map data quarter: "+currVersion.getDataQuarter());}catch(CopilotExceptione){e.printStackTrace();}
Allows the integrated application to set a time delay between the notification that a turn instruction is about to be played and when CoPilot actually starts to speak. This is used to delay the announcement, allowing for the muting of other audio such as a radio or a third-party application announcement.
The delay is in milliseconds, and will impact the onReadyToSpeakTurnInstruction and onSpeakTurnInstructionComplete.
Supported on Android Since Version
9.6.0.821
Supported on iOS Since Version
10.9
Type
Method
Package
com.alk.cpik
Syntax
voidsetTurnInstructionCallbackDelay(intdelay)
+(void)setTurnInstructionCallbackDelay:(int)
Parameters
Delay – The number of milliseconds for which to delay the time between turn instruction callbacks and speech instructions. Must be between 0 and 2000, inclusive.
Sample Code
try{// Set the delay to 1.5 secondsintdelayMilliSecond=1500;CopilotMgr.setTurnInstructionCallbackDelay(delayMilliSecond);System.out.println("TurnInstructionCallbackDelay is set for "+delayMilliSecond+" millisecond");}catch(CopilotExceptione){e.printStackTrace();}
[CopilotMgrsetTurnInstructionCallbackDelay:500];
CopilotMgr.getTurnInstructionCallbackDelay
Overview
Description
Retrieves the current time delay between the notification a turn instruction is about to be played and when CoPilot actually starts to speak. The delay is in milliseconds.
Supported on Android Since Version
9.6.0.821
Supported on iOS Since Version
10.9
Type
Method
Package
com.alk.cpik
Syntax
intgetTurnInstructionCallbackDelay()
+(int)getTurnInstructionCallbackDelay
Return Value
Returns an int value to represent delay in milliseconds.
Sample Code
try{// Print the current turn instruction delayintcurrDelayMs=CopilotMgr.getTurnInstructionCallbackDelay();System.out.println("Current delay: "+String.valueOf(currDelayMs)+"milliseconds");}catch(CopilotExceptione){e.printStackTrace();}
Retrieves the view associated with the CoPilot service. CoPilot only has one view; multiple calls to this function will return the same instance. In order to reuse the view, it must be removed from its parent. If CoPilot should have focus, requestFocus() must be used instead.
Supported on Android Since Version
9.6.0.821
Type
Method
Package
com.alk.cpik
Syntax
ViewgetView
Parameters
None
Return Value
android.view.View object
Sample Code
// getting current CoPilot viewViewv=CopilotMgr.getView();// View needs focus in order to bring up the keyboard and handle navigation within CoPilot with the back buttonv.requestFocus();
CopilotMgr.isActive
Overview
Description
Determines whether or not CoPilot is able to receive API calls. APIs can be called only after onCPStartup is sent and before onCPShutdown returns.
Supported on Android Since Version
9.6.0.821
Type
Method
Package
com.alk.cpik
Syntax
booleanisActive()
Parameters
None.
Return Value
Boolean - True if CoPilot is ready to receive API calls, false otherwise.
Sample Code
// Print whether or not CoPilot is ready to receive API callsif(CopilotMgr.isActive())System.out.println("CoPilot is ready to receive API calls.");elseSystem.out.println("CoPilot is NOT ready to receive API calls.");
CopilotMgr.setCopilotStartupParameters
Overview
Description
Sets a CopilotStartupParams object that contains overridden methods used during CoPilot Startup.
Restarts the CoPilot GPS Service and resumes all suspended activities following the API call CopilotMgr.disableGPS(). CoPilot will register with the GPS receiver to initiate listening and processing the current position again.
Supported on Android Since Version
9.6.0.1184
Supported on Android Since Version
10.9
Type
Method
Package
com.alk.cpik
Syntax
voidenableGPS()
Parameters
None.
Return Value
void
Sample Code
try{// Resume CoPilot GPS ServiceCopilotMgr.enableGPS();System.out.println("GPS is enabled.");}catch(CopilotExceptione){e.printStackTrace();}
[CopilotMgrenableGPS];
CopilotMgr.disableGPS
Overview
Description
Attempts to minimize CPU usage by suspending background GPS/routing processing and unregistering the CoPilot GPS Service. Background navigation will not work after this API call; this will mean that your application cannot retrieve updated ETA or distance information.
Supported on Android Since Version
9.6.0.1184
Supported on iOS Since Version
10.9
Type
Method
Package
com.alk.cpik
Syntax
voiddisableGPS()
Parameters
None.
Return Value
void
Sample Code
try{// Unregister the CoPilot GPS serviceCopilotMgr.disableGPS();System.out.println("GPS is disabled.");}catch(CopilotExceptione){e.printStackTrace();}
[CopilotMgrdisableGPS];
CopilotMgr.setBillingProvider
Overview
Description
Sets a third-party, in-app billing provider that should be used by CoPilot for in-app billing operations. This requires implementation of the IBillingProviderInterface interface. This requires integration with googleplaybilling.jar which is included in the “Library and Resources/jars” folder of the initial application delivery.
billingProvider - Implementation of the com.alk.copilot.IBillingProviderInterface interface.
Return Value
void
Sample Code
// Set billing providerfinalintbillingRequestCode=1;ActivityactivityPointer=newMainActivity();IBillingProviderInterfacebillingProvider=newBillingManager(activityPointer,billingRequestCode);// user can use 'this' instead of activityPointerCopilotMgr.setBillingProvider(billingProvider);
CopilotMgr.addFavorite
Overview
Description
Adds a new favorite location (address or point of interest) to CoPilot’s favorite list. FavoriteStop must be geocoded and the lat/long set within FavoriteBuilder before calling this API. Once favorites have been successfully added, they will be available for the driver to select in the CoPilot address entry screen. Favorites can be assigned a name and address, and they can also be set to different types, including Home, Work, and General.
// Add a new favorite to CoPilotFavoriteBuilderfavoriteBuilder=newFavoriteBuilder();favoriteBuilder.setName("Trimble Maps");favoriteBuilder.setStreetAddress("457 N Harrison St");favoriteBuilder.setCity("Princeton");favoriteBuilder.setState("NJ");favoriteBuilder.setZip("08540");favoriteBuilder.setFavoriteType(Favorite.FavoriteType.GENERAL);Favoritefavorite=favoriteBuilder.build();CopilotMgr.addFavorite(favorite);
Removes unwanted locations from CoPilot’s favorite list. The favorite list can be retrieved by calling CopilotMgr.getFavoritesList(). Once successfully removed, the driver will no longer see the unwanted locations in CoPilot.
Supported on Android Since Version
9.6.0.821
Supported on iOS Since Version
10.9
Type
Method
Package
com.alk.cpik.trip
Syntax
voidremoveFavorite(int)
(void)removeFavorite:(int)
Parameters
Index - The index of the location to be removed within the favorites list, as returned by a call to CopilotMgr.getFavoritesList().
Sample Code
// Remove a favoriteList<Favorite>favoriteList=CopilotMgr.getFavoritesList();// Remove the first favorite in above favoriteListintindexToRemove=0;CopilotMgr.removeFavorite(indexToRemove);System.out.println("Favorite "+favoriteList.get(indexToRemove).toString()+" is removed.");
[CopilotMgrremoveFavorite:0];
CopilotMgr.getFavoritesList
Overview
Description
Returns the list of all favorites currently stored in CoPilot’s favorites list. This list will match the complete list available within the CoPilot address search menu.
Supported on AndroidSince Version
9.6.0.821
Supported on iOS Since Version
10.9
Type
Method
Package
com.alk.cpik
Syntax
java.util.ListgetFavoritesList()
+(NSArray*)getFavoriteList
Return Value
java.util.List - Returns the list of favorites currently stored in CoPilot’s favorites list.
Sample Code
// Print out the list of favoritesList<Favorite>favoriteList=CopilotMgr.getFavoritesList();for(intcurrFavIndex=0;currFavIndex<favoriteList.size();currFavIndex++){FavoritecurrentFavorite=favoriteList.get(currFavIndex);System.out.println("Favorite Type "+currentFavorite.getFavoriteType());System.out.println("Favorite Name "+currentFavorite.getName());System.out.println("Favorite Address "+currentFavorite.getAddress());System.out.println("Favorite City "+currentFavorite.getCity());System.out.println("Favorite Country "+currentFavorite.getCountry());System.out.println("Favorite Zip "+currentFavorite.getZip());System.out.println("Favorite State "+currentFavorite.getState());System.out.println("Favorite Coordinate "+currentFavorite.getCoordinate());//to get all values at the same time we can useSystem.out.println(currentFavorite.toString());}