Skip to content

Hooks and Callbacks

Listeners Explained

A callback is a method that is called at a particular time in the code, often for logging purposes. An outside application can create listeners that detect when these methods are called, and act accordingly by defining the methods. A hook is the same as a callback, but also demands that a value be returned from the outside application when detected by the listener. This allows communication between CoPilot and the software that is integrating it.

CopilotListener

Callbacks related to CoPilotMgr

onCPStartup
Method JavaScript: onCPStartup = () =>
Type: Callback
Description: Called when CoPilot has finished initializing.
onCPShutdown()
Method JavaScript: onCPShutdown = () =>
Type: Callback
Description: Called when CoPilot has finished shutting down.

RouteListener

Callbacks related to RouteMgr

onGPSFixChanged
Method JavaScript: onGPSFixChanged = (status) =>
Callback Data: GPSFixQuality
Data Type: Native Module Constant
Description: This Callback is called whenever the GPS fix has been acquired, lost or changed.
onStopsAdded
Method JavaScript: onStopsAdded = (stops) =>
Callback Data: Array of Stop JSON Objects
Data Type: JSON Array
Description: Called when one or more stops have been added to the current trip. If a trip exists and then a new trip is planned, onStopsDeleted() is called, followed by onStopsAdded()
onStopsDeleted
Method JavaScript: onStopsDeleted = (stops) =>
Callback Data: Array of Stop JSON Objects
Data Type: JSON Array
Description: onStopsDeleted will be called if stops are successfully deleted. The callback also returns a list of stops that were deleted. For RouteMgr.deleteStop, the returned stop list should only have one element. But for RouteMgr.removeAllStops, the return stop list can have more than one elements.
onStartRouteCalculation
Method JavaScript: onStartRouteCalculation = () =>
Type: Callback
Description: Called when a route has started to be calculated.
onCompleteRouteCalculation
Method JavaScript: onCompleteRouteCalculation = () =>
Type: Callback
Description: Called when a route calculation was completed.
onFailedRouteCalculation
Method JavaScript: onFailedRouteCalculation = (cbData) =>
Callback Data: "legNum": int,
"badStop": Stop
Data Type: JSON Object
Description: Called when a route calculation failed.

GuidanceListener

Callbacks from the APIs in GuidanceMgr

onArrivedAtStop
Method JavaScript: onArrivedAtStop = (cbData) =>
Callback Data: "isFinalStop": boolean
"arrivalStatus": ArrivalStatus
"stop": Stop
Data Type: JSON Object
Description: Callback is provided when a user has registered a GuidanceListener with the onArrivedAtStop class. Uses the native module ArrivalStatus, to provide status details of the stop.

The approaching and arrival status messages are controlled by a set of configuration values that can be set within the product/user configuration file. [User Settings] “ApproachingStopDistHundredths”, and “ArrivedStopDistHundredths” options both indicate the distance threshold, in hundredths of a mile, from your stop, where the user will see the prompt (popup, sound, or speech) to be shown. The defaults are:

  • [User Settings]
    “ApproachingStopDistHundredths”=5 // (~250 feet)
    “ArrivedStopDistHundredths”=-1 // (default is OFF)

  • If you would like the Arrived prompt, it is recommended to prompt at 1 or 2 hundredths of a mile (50 or 100 feet from the stop). “ArrivedStopDistHundredths“=1 or 2

  • [GPS] “SpeakApproachingDestinationInstr”, “SpeakArrivedAtDestinationInstr”, “PlayArrivedAtDestinationSound”, “PlayApproachingDestinationSound” can be used to modify how CoPilot indicates “Approaching or Arrived” status (whether prompted with Text To Speech, sound, or no prompt). The onArrivedAtStop callback will fire regardless of these settings. If they are all accidentally set to on, the Speech announcement will prompt.

  • [User Settings] “ShowArrivalPopup” can be used to request CoPilot DOES NOT show the Arrival Popup. Showing or not showing the popup, does NOT have any affect on whether or not the status event is fired through SDK Libraries.

onTruckWarningUpdate
Method JavaScript: onTruckWarningUpdate = (info) =>
Callback Data: TruckWarning
Data Type: JSON Object
Description: Called when there is a truck warning update.
onOverSpeedLimitEvent
Method JavaScript: onOverSpeedLimitEvent = (warning) =>
Callback Data: OverSpeedLimitWarning
Data Type: JSON Object
Description: Called when there is a warning for traveling over the speed limit.
onCrossedCountryBorder
Method JavaScript: onCrossedCountryBorder = (country) =>
Callback Data: Country
Data Type: JSON Object
Description: Called when navigating into a new country.
onETAChanged
Method JavaScript: onETAChanged = (newEta) =>
Callback Data: String representing of ETA
Data Type: String
Description: Called when the ETA for the current trip has changed by a minute or more.
onEstimatedTravelTimeUpdated
Method JavaScript: onEstimatedTravelTimeUpdated = (cbData) =>
Callback Data: "hoursOfTravel": int
"minutesOfTravel": int
Data Type: JSON Object
Description: Called when the ETT for the current trip has changed by a minute or more.
onDistanceToDestinationUpdated
Method JavaScript: onDistanceToDestinationUpdated = (distanceToDestination) =>
Callback Data: Int representing for distance to destination
Data Type: Int
Description: Called whenever CoPilot computes the distance to destination (could be approximately.
onPositionUpdate
Method JavaScript: onPositionUpdate = (info) =>
Callback Data: PositionInfo
Data Type: JSON Object
Description: Called whenever there is additional position information
onTurnInstructionEvent
Method JavaScript: onTurnInstructionEvent = (guidanceInformation) =>
Callback Data: TurnInstruction
Data Type: JSON Object
Description: Called when new guidance information is available.
onTrafficInfoProcessedForCurrentRoute
Method JavaScript: onTrafficInfoProcessedForCurrentRoute = () =>
Type: Callback
Description: Called when traffic information received and processed from the traffic server for the current route. Customer application get the ETA as well traffic delay by using the RouteMgr.getRouteLegs().get(0).getETA() and RouteMgr.getRouteLegs().get(0).getTrafficDelay() respectively.
onStopArrivalStatusChange
Method JavaScript: onStopArrivalStatusChange = (stops) =>
Callback Data: Array of Stop JSON Objects
Data Type: JSON Array
Description: Called when a driver's stop's status changes (e.g OnTime to Late). The callback will return a list of stops who status have been changed.

MapDataListener

Callbacks from MapDataMgr

onMapDownloadResponse
Method JavaScript: onMapDownloadResponse = (cbData) =>
Callback Data: "response": MapDownloadResponse
"requestedRegions": Array of MapRegions
"overwriteExistingMaps": boolean
Data Type: JSON Object
Description: Called with the download response of a map data download
onMapdataUpdate
Method JavaScript: onMapdataUpdate = (cbData) =>
Callback Data: "mapSet": MapInfo
"status": DownloadStatus
Data Type: JSON Object
Description: Called when there is an update on a map download.
onMapSureOverrideSyncStarted
Method JavaScript: onMapSureOverrideSyncStarted = () =>
Type: Callback
Description: Called when CoPilot has started a MapSure sync in response to a call to the API getMapSureOverride().
onMapSureOverrideSyncFailed
Method JavaScript: onMapSureOverrideSyncFailed = () =>
Type: Callback
Description: Called when CoPilot has triggered a MapSure sync in response to a call to the API getMapSureOverride() but it has failed.
onMapSureOverrideSyncSuccess
Method JavaScript: onMapSureOverrideSyncSuccess = (cbData) =>
Callback Data: "successful": int
"failed": int
Data Type: JSON Object
Description: Provides notification that a MapSure Override sync has completed and it includes the number of edits that have been successfully updated and the number that have failed

LicenseListener

LicenseListeners are hooks and callbacks from LicenseMgr

onLicenseMgtLogin
Available in CoPilot 10.14.0.487 and Higher
Method JavaScript: onLicenseMgtLogin = (cbData) =>
Type: Callback
Data Type: JSON Object
"status": LicenseActivationResponse
"loginInfo": LicenseMgtInfo
Description: Called when login using the Account Manager is finished.
onLicensingReady
Method JavaScript: onLicensingReady = () =>
Type: Callback
Description: Called when CoPilot is ready to accept licenses to be activated.
mapRegionUpgradeKeyHook Android Only
Method JavaScript: mapRegionUpgradeKeyHook = () =>
Type: Callback
Description: This is called on first start when a region upgrade key has not yet been applied. The user provides an upgrade key to activate a region.

OptimizationListener

Callbacks related to OptimizationMgr

onOptimizationProgress
Method JavaScript: onOptimizationProgress = (optNotification) =>
Callback Data: OptimizationNotification
Data Type: Native Module Constant
Description: Called to provide progress update for Optimization.
onOptimizationError
Method JavaScript: onOptimizationError = (optError) =>
Callback Data: OptimizationError
Data Type: Native Module Constant
Description: Called to provide error encountered during the Optimization. Optimization will be stopped after getting this error.
onOptimizationStopError
Method JavaScript: onOptimizationStopError = (cbData) =>
Callback Data: "stopError": OptimizationStopError
"stopNo": int
Data Type: JSON Object
Description: Called to provide stop error encountered during the Optimization. Optimization engine will still go ahead by ignoring those stops.
onOptimizationStopGeocode
Method JavaScript: onOptimizationStopGeocode = (cbData) =>
Callback Data: "stopNo": int
"latLon": Coordinate
"error": int
Data Type: JSON Object
Description: Called to provide geocode results where stops having address data but does not contain the latitude/longitude.
onOptimizationResult
Method JavaScript: onOptimizationResult = (cbData) =>
Callback Data: "finalETA": int
"totalDistance": double
"optOutStops": OptimizationOutStop
Data Type: JSON Object
Description: Called to provide Optimization result once Optimization finished. It will provide final ETA, total distance as well individual stop’s optimization number, ETA and distance.

Last update: August 26, 2020