Skip to main content

Hooks and Callbacks (React Native)

Contents

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. We recommend that you shut down the service only when necessary. It is also best to wait at least 2 or 3 seconds to restart CoPilot after you shut it down. Restarting too frequently or too quickly can cause the application to crash.
onMinimize() (Android only)
Method JavaScript: onMinimize= () => {}
Type: Callback
Description: Called when the user presses the back button in the CoPilot navigation dialog.
onFavoriteAdded()
Method JavaScript: onFavoriteAdded= () => {}
Type: Callback
Description: Called when a Favorite is added to CoPilot.
onFavoriteEdited()
Method JavaScript: onFavoriteEdited= () => {}
Type: Callback
Description: Called when a Favorite is edited in CoPilot.
onFavoriteDeleted()
Method JavaScript: onFavoriteDeleted= () => {}
Type: Callback
Description: Called when a Favorite is deleted in CoPilot.
onMapStopClicked
Method JavaScript: onMapStopClicked= (stopClicked) => {}
Type: StopClickInfo
Data Type: JSON object
Description: Called whenever the user clicks on the destination or waypoint on the map.
onMapPOIClicked()
Method JavaScript: onMapPOIClicked= (list) => {}
Type: Array of POISearchResult
Data Type: JSON Array
Description: Returns a list of POISearchResult that represents the POIs at the clicked location.
onMapSelectionCleared()
Method JavaScript: onMapSelectionCleared= () => {}
Type: Callback
Description: Called when the user has clicked on the map in one of two situations:
1. The user had previously clicked on the map to select a POI, Road, or Stop, and the user clicks on the map off of that, which would clear the selection.
2. The user has clicked on the map in a location where there is no selection.
onSingleSearchFinished()
Callback Data: “stopList”: Array of Stop JSON objects
“Error”: SingleSearchError object
Data Type: JSON Object
Description: Called when a single search web service gives back the response and gives a list of Stops and SingleSearchError result.
onSingleSearchReady()
Method JavaScript: onSingleSearchReady= () => {}
Type: Callback
Description: Called when single search has finished initializing

POIListener

Callbacks related to CoPilotMgr

onPOIAlert()
Method JavaScript: onPOIAlert= (alerts) => {}
Callback Data: Array of POIAlert JSON objects
Data Type: Array
Description: Called as POI updates are received.
onPOISearchResults()
Method JavaScript: onPOISearchResults= (cbData) => {}
Callback Data: poiSearchResult: Array of POISearchResult JSON objects
bSearchComplete: boolean indicating whether the search is done.
Data Type: JSON object
Description: Called as POI search results update. This callback will be called continuously as the POI search list grows.

GuidanceListener

Callbacks from the APIs in GuidanceMgr.

onPedestrianLink()
Method JavaScript: onPedestrianLink= () => {}
Type: Callback
Description: Called whenever a stop is on a pedestrian only road link.
onEnvironmentalZone()
Method JavaScript: onEnvironmentalZone= (environmentalZones) => {}
Callback Data: Array of EnvironmentalZoneType JSON
Data Type: JSON object
Description: Called whenever a stop or a route passes through the London congestion zone, Environment Zone or ULEZ zone. It is called when CoPilot identifies a road or destination as truck restricted.
onTruckRestricted()
Method JavaScript: onTruckRestricted= (truckRestrictionType) => {}
Callback Data: TruckRestrictionType constant
Data Type Constant
Description: Called when a driver is on a truck-restricted, commercial-prohibited, or hazmat-restricted road; or a width/length/height/weight restricted road; or a stop is located on one of those types of restricted roads.
onTrafficAlert()
Method JavaScript: onTrafficAlert= (trafficAlertInfo) => {}
Callback Data: TrafficAlertInfo JSON object
Data Type JSON object
Description: Called in the following scenarios:
1. A delay due to traffic with alternate route info.
2. Road closure
3. A sudden slowdown in a few miles that warns the driver to use caution.
onSafetyCamUpdate()
Method JavaScript: onSafetyCamUpdate= (safetyCam) => {}
Callback Data: SafetyCamera JSON object
Data Type JSON object
Description: Called when new guidance safety camera information is available. NOTE: This API requires the CoPilot library to be licensed for Basic Navigation.
onShowLaneAssist
Method JavaScript: onShowLaneAssist= (laneAssistInfo) => {}
Callback Data: LaneAssistInfo JSON object
Data Type JSON object
Description: Called when lane assist information is available for the current road segment.
onHideLaneAssist()
Method JavaScript: onHideLaneAssist= () => {}
Type: Callback
Description: Called when lane assist information should no longer be displayed to the user.
onSpeedLimitChanged
Method JavaScript: onSpeedLimitChanged= (cbData) => {}
Callback Data: speedLimit: int indicating the new speed limit.
truckSpeedLimit: int indicating the new speed limit for trucks.
Data Type JSON object
Description: Called each time the current speed limit changes.
onItineraryUpdated()
Method JavaScript: onItineraryUpdated= () => {}
Type: Callback
Description: Called when itinerary is changed in CoPilot.
onRoadClassChanged
Method JavaScript: onRoadClassChanged= (cbData) => {}
Callback Data: previousRoadClass: previous RoadClass you were driving on.
currentRoadClass: current RoadClass you are driving on.
Data Type JSON object
Description: Called when the road class changes.

LicenseListener

LicenseListeners are hooks and callbacks from LicenseMgr.

onFeatureActivated()
Method JavaScript: onFeatureActivated= (feature) => {}
Type: Callback
Data Type LicenseFeature constant
Description: Called when a license is successfully activated. This callback is fired once for each feature.
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.

RouteListener

Callbacks related to RouteMgr

onStopsMoved()
Method JavaScript: onStopsMoved = (stops) => {}
Callback Data: Array of Stop JSON Objects
Data Type JSON array
Description: Called when the order of stops changes in the current trip.
onStopsReplaced()
Method JavaScript: onStopsReplaced = (stops) => {}
Callback Data: Array of Stop JSON Objects
Data Type JSON array
Description: Called when one or more stops have been replaced in the current trip. Callback data is list of new stops.
onRouteSyncError()
Method JavaScript: onRouteSyncError= (error) => {}
Callback Data: A RouteSyncError constant
Data Type Native Module Constant
Description: Called when there was an error processing a RouteSync route. This callback will also fire if there were any errors processing a saved managed route when CPIK starts. These events can be captured by listeners that are registered before starting the CoPilot service.
onRouteSyncIntegrated()
Method JavaScript: onRouteSyncIntegrated= (routeName) => {}
Callback Data: A String containing the route name.
Data Type String
Description: Called after a routesync route has successfully been integrated.
onOutOfRoute()
Method JavaScript: onOutOfRoute= (cbData) => {}
Callback Data: timeOfDeviation: Date object containing the date and time of when the driver deviated from the prescribed route
pointOfDeviation: RouteSyncLocation JSON object containing the point at which the driver deviated from the route.
Data Type JSON Object
Description: Called when Copilot detects that the device is out of route.
onRejoinRoute()
Method JavaScript: onRejoinRoute= (cbData) => {}
Callback Data: timeOfRejoin: Date object containing the date and time of when the driver rejoin the prescribed route.
pointOfRejoin: RouteSyncLocation JSON object containing the point at which the driver rejoined the route.
outOfRouteDistanceTraveled: Double containing the distance traveled while out of route.
Data Type JSON Object
Description: Called when Copilot detects that the device has rejoined the route. Contains data concerning the duration and distance traveled while out of route.
onStartAlternateRouteCalculation()
Method JavaScript: onStartAlternateRouteCalculation= () => {}
Type Callback
Description: Called when an alternate route calculation starts in CoPilot.
onAlternateRouteSelected()
Method JavaScript: onAlternateRouteSelected= (tripID) => {}
Callback Data: Int containing the TripID of the selected route.
Data Type Integer
Description: Called when user selects the alternate route in the alternate route dialog.
onRouteCalculation()
Method JavaScript: onRouteCalculation= (alternateRouteInfo) => {}
Callback Data: AlternateRouteInfo JSON object
Data Type JSON Object
Description: Called when CoPilot calculates the base route and alternate routes or when CoPilot finds a traffic delay for the base route and calculates an alternate route.
onStartChangeVehicleType()
Method JavaScript: onStartChangeVehicleType= (vehicleType) => {}
Callback Data: VehicleType constant
Data Type Native Module Constant
Description: This callback is fired with the current vehicle type when CoPilot is getting ready.
onFinishChangeVehicleType()
Method JavaScript: onFinishChangeVehicleType= (vehicleType) => {}
Callback Data: VehicleType constant
Data Type Native Module Constant
Description: This callback is fired with the new vehicle type when CoPilot changes it.
onManagedRouteStatusChanged()
Method JavaScript: onManagedRouteStatusChanged= (ManagedRouteInfo) => {}
Callback Data: ManagedRouteInfo JSON Object
Data Type JSON object
Description: Called when a managed route is active, completed, or canceled.
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.
onReadyToAddStops
Method JavaScript: onReadyToAddStops= () => {}
Type: Callback
Description: This callback is only called at startup when CoPilot is ready to add stops. It will not be called each time you add a new stop to your trip. However, if there is an existing route already in CoPilot, this callback will be fired when you re-launch CoPilot.
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 CPIK 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 is received and processed from the traffic server for the current route. The customer application gets the ETA as well traffic delay information by using 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.

GeofenceListener

Callbacks related to GeofenceMgr

onGeofenceEntry
Method JavaScript: onGeofenceEntry = (callbackData) => {}
Callback Data: “geofence”: Geofence
“position”: Coordinate
“time”: Date
Data Type: JSON Object
Description: Called when the current position enters a geofence that has an entry notification sent. Contains details on the geofence that was entered, the position at which the geofence was entered, and the time at which the geofence was entered.
onGeofenceExit
Method JavaScript: onGeofenceExit = (callbackData) => {}
Callback Data: “geofence”: Geofence
“position”: Coordinate
“time”: Date
Data Type: JSON Object
Description: Called when the current position leaves a geofence that has an exit notification sent. Contains details on the geofence that was exited, the position at which the geofence was exited, and the time at which the geofence was exited.
onGeofenceRouteThrough
Method JavaScript: onStopsDeleted = (stops) => {}
Callback Data: Array of Geofence JSON Objects
Data Type: JSON Array
Description: Called when a route is calculated which passes through any geofences which have the route through notification set.

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

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.

SpeechListener

Callbacks related to SpeechMgr.

onReadyToSpeakTurnInstruction()
Method JavaScript: onReadyToSpeakTurnInstruction= () => {}
Type: Callback
Description: Called when CoPilot is about to play a turn instruction.
onSpeakTurnInstructionComplete()
Method JavaScript: onSpeakTurnInstructionComplete= () => {}
Type: Callback
Description: Called when CoPilot has finished playing a turn instruction.
onReadyToSpeakUtterance()
Method JavaScript: onReadyToSpeakUtterance= () => {}
Type: Callback
Description: Called when CoPilot is about to speak anything, including a turn instruction.
onSpeakUtteranceComplete()
Method JavaScript: onSpeakUtteranceComplete= () => {}
Type: Callback
Description: Called when CoPilot has finished speaking anything, including a turn instruction.
onVoiceDownloadStatusUpdate()
Method JavaScript: onVoiceDownloadStatusUpdate= (cbData) => {}
Callback Data: Status: VoiceDownloadStatus of the voice download.
voiceInfo: VoiceInfo JSON object containing information about the voice being downloaded.
Data Type: JSON Object
Description: Called when there is an update on the download status of a voice.
onSpeakTurnInstruction()
Method JavaScript: onSpeakTurnInstruction= (turnInstruction) => {}
Callback Data: turnInstruction contains the text that is about to be spoken
Data Type: String
Description: Called when CoPilot is about to speak using a Text-to-Speech (TTS) String.
onAfterSoundPlayed()
Method JavaScript: onAfterSoundPlayed= () => {}
Type: Callback
Description: Called after a sound has finished playing.

SiteListener

onSiteEntry
Method JavaScript: onSiteEntry = (callbackData) => {}
Callback Data: “site”: Site
“entryPoint”: Coordinate
Data Type: JSON Object
Description: Called when CoPilot’s GPS position enters the bounds of a Site polygon’s coordinates.
onSiteExit
Method JavaScript: onSiteExit = (callbackData) => {}
Callback Data: “site”: Site
“exitPoint”: Coordinate
Data Type: JSON Object
Description: Called when CoPilot’s GPS position leaves the bounds of a Site polygon’s coordinates.

UiListener

Callbacks related to UIMgr.

onShowNavigationScreen()
Method JavaScript: onShowNavigationScreen= (mapView) => {}
Callback Data: A MapViewType constant
Data Type: Native Module Constant
Description: Called when the navigation screen (map) is shown.
onLeaveNavigationScreen()
Method JavaScript: onLeaveNavigationScreen= () => {}
Type: Callback
Description: Called when the navigation screen (map) is hidden.
onStartingPoiWizard()
Method JavaScript: onStartingPoiWizard= () => {}
Type: Callback
Description: Called when the Points of Interest (POI) search wizard is about to start. This is called from both the driving menu (from the navigation screen) and the main menu.
Last updated May 13, 2024.
Contents