Class: EvamApi¶
EvamApi.EvamApi
Evam API singleton that exposes methods to interact with the Evam platform.
When using any method, pay attention to the permission they require, you will need to add them to your Evam manifest. In general, try to limit how many permissions your certified app requires as more permissions may cause a longer review process when deploying your certified app.
Example
// Get instance (don't be afraid to copy them around or create more, as they're simply a lightweight reference to shared static data)
const evamApi = new EvamApi();
// Register a new callback on any operation update that simply logs it
evamApi.onNewOrUpdatedActiveOperation((activeOperation) => console.log(activeOperation));
// Register a new callback on any application settings update that simply logs them
evamApi.onNewOrUpdatedSettings((settings) => console.log(settings));
//Register a new callback to any specific application data update. Available register methods:
evamApi.onNewOrUpdatedDeviceRole((deviceRole) => ...);
evamApi.onNewOrUpdatedLocation((location) => ...);
evamApi.onNewOrUpdatedInternetState((internetState) => ...);
evamApi.onNewOrUpdatedVehicleState((vehicleState) => ...);
evamApi.onNewOrUpdatedTripLocationHistory((tripLocationHistory) => ...);
// Send a new notification to VS (this will also work for the developer environment)
// This will display a notification with heading "example", description "lorem ipsum". It will have type 'QUICK_HUN' and a primary button
// which is labelled 'primary button' that doesn't do anything when called. The secondary button is not defined, thus it will not display.
evamApi.sendNotification(new Notification("example","lorem ipsum", NotificationType.QUICK_HUN, {label:'primary button', callback:()=>{}}, undefined))
//Remove all callbacks from the SDK (this is useful for cleanup)
evamApi.unsubscribeFromAllCallbacks()
//Detect whether the certified app is currently running in Vehicle Services
EvamApi.isRunningInVehicleServices
//update the current hospital by id (be sure that the hospital is listed in available hospitals)
evamApi.setHospital(1234)
//update the current priority (be sure that the priority is listed in available priorities)
evamApi.setPriority (1)
//simulate Vehicle Services data inject (development + testing only)
//DO NOT USE THESE METHODS IN PRODUCTION, While not breaking by any means they will not perform any function.
evamApi.injectLocation(new Location(59.364, 18.012, new Date()))
evamApi.injectVehicleState(new VehicleState(...))
evamApi.injectTrip(new TripLocationHistory(...))
evamApi.injectDeviceRole(new DeviceRole(...))
evamApi.injectInternetState(new InternetState(...))
evamApi.injectOperation(new Operation(...))
evamApi.injectSettings(new Settings(...))
evamApi.injectOperationList([new Operation(...), new Operation(...), ...])
evamApi.injectBattery(new Battery(...)))
Constructors¶
constructor¶
new EvamApi()
Properties¶
store¶
store: Object
Store used for persisting data within Vehicle Services. If you are in development and not running your application within vehicle services then this will serve as a lightweight wrapper around localstorage. To avoid naming conflicts AppId must be set as it is used to identify application items.
Type declaration¶
Name |
Type |
---|---|
|
() => |
|
( |
|
( |
|
( |
isRunningInVehicleServices¶
Static
isRunningInVehicleServices: boolean
= isRunningInVehicleServices
Notifications Methods¶
removeNotification¶
removeNotification(notificationId
): void
Removes the notification by given id.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The notification id |
Returns¶
void
Requires
Permissions SEND_NOTIFICATION
Requires
Version Vehicle Services version 5.2.2 and above have full functionality. Other versions: function will throw an Error.
Requires
Environment Evam device only
sendNotification¶
sendNotification(notification
): void
Send a notification to Vehicle Services.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
The notification to be sent |
Returns¶
void
Requires
Permissions SEND_NOTIFICATION
Requires
Version Vehicle Services version 5.1.0 and above have full functionality. Other versions: function with throw an Error.
Requires
Environment Evam device only
Operations Methods¶
onNewOrUpdatedActiveOperation¶
onNewOrUpdatedActiveOperation(callback
): void
Registers a callback to be run upon a new Active Operation is available or the current Active Operation is updated.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The callback to be executed |
Returns¶
void
Requires
Permissions ACTIVE_OPERATION_READ
Requires
Version Vehicle Services version 5.0.0 and above have full functionality. Other versions: callback will never trigger.
Trigger
The callback triggers every time the active Operation is updated, this can happen due to update by the dispatch (e.g. SOS), Evam Demo Tool or user edit (e.g. change of PRIO)
onNewOrUpdatedAvailableVehicleStatusList¶
onNewOrUpdatedAvailableVehicleStatusList(callback
): void
Used to assign a callback when the list of available Vehicle Statuses is created or updated
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The callback with (optional) argument available Vehicle Status list. Use this to access the available Vehicle Statuses. |
Returns¶
void
Requires
Permissions AVAILABLE_VEHICLE_STATUS_LIST_READ
Requires
Version Vehicle Services version 5.1.0 and above have full functionality. Other versions: callback will never trigger.
Trigger
The callback triggers every time the list of available Vehicle Statuses is updated for this vehicle, and also when the certified app starts.
onNewOrUpdatedOperationList¶
onNewOrUpdatedOperationList(callback
): void
Used to assign a callback when the operation list is updated.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The callback with (optional) argument operationList. Use this to access the operation list. |
Returns¶
void
Requires
Permissions OPERATION_READ
Requires
Version Vehicle Services version 5.1.0 and above have full functionality. Other versions: callback will never trigger.
Trigger
The callback triggers every time any Operation is updated in the Evam platform, including the Active one.
onNewOrUpdatedVehicleState¶
onNewOrUpdatedVehicleState(callback
): void
Used to assign a callback when the vehicle state is updated.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The callback with (optional) argument vehicleState. Use this to access the vehicle state. |
Returns¶
void
Requires
Permissions VEHICLE_STATE_READ
Requires
Version Vehicle Services version 5.0.0 and above have full functionality. Other versions: callback will never trigger.
Trigger
The callback triggers every time any of the following is updated: device location, Operation ID, Vehicle Status.
setHospital¶
setHospital(id
): void
Sets the selected hospital id for the current active operation. The id must be present inside the available hospitals
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
the id of the hospital to be set |
Returns¶
void
Requires
Permissions ACTIVE_OPERATION_WRITE
Requires
Version Vehicle Services version 5.0.2 and above have full functionality. Other versions: function will throw an Error.
setPriority¶
setPriority(id
): void
Sets the selected priority id for the current active operation. The id must be present inside the available priorities.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
of the priority to be set |
Returns¶
void
Requires
Permissions ACTIVE_OPERATION_WRITE
Requires
Version Vehicle Services version 5.0.2 and above have full functionality. Other versions: function will trigger an error.
Other Methods¶
getAppId¶
getAppId(): string
Gets the Evam App id as given by Vehicle Services
Returns¶
string
getAppVersion¶
getAppVersion(): string
Gets the Evam App version as defined in the evam.json manifest
Returns¶
string
getDeviceId¶
getDeviceId(): string
Gets the device ID as defined in Android
Returns¶
string
getGRPC¶
getGRPC(): GRPC
Gets the address for the GRPC proxy
Returns¶
getOSVersion¶
getOSVersion(): string
Gets the Android OS version
Returns¶
string
getVehicleServicesVersion¶
getVehicleServicesVersion(): string
Gets the Vehicle Services app version
Returns¶
string
unsubscribeFromAllCallbacks¶
unsubscribeFromAllCallbacks(): void
Unsubscribes all registered callbacks from Vehicle Service events.
Returns¶
void
Radio Methods¶
onNewOrUpdatedRakelMessages¶
onNewOrUpdatedRakelMessages(callback
): void
Used to assign a callback when the incoming Rakel messages are updated. The messages are piped though in the raw form as they are received from the radio.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The callback with (optional) argument Rakel messages. Use this to access the incoming Rakel messages. |
Returns¶
void
Requires
Permissions RAKEL_COMMUNICATION_READ
Requires
Version Vehicle Services version 5.2.0 and above have full functionality. Other versions: callback will never trigger.
Trigger
The callback triggers every time new messages are available from the connected Tetra terminal.
onNewOrUpdatedRakelState¶
onNewOrUpdatedRakelState(callback
): void
Used to assign a callback when the rakel state is created or updated
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The callback with (optional) argument Rakel state. Use this to access the Rakel state. |
Returns¶
void
Requires
Permissions RAKEL_STATE_READ
Requires
Version Vehicle Services version 5.2.0 and above have full functionality. Other versions: callback will never trigger.
Trigger
The callback triggers every time any of the following changes: GSSI, MSISDN, ISSI of the connected radio. Also, when the certified app starts.
sendRawRakelAction¶
sendRawRakelAction(rawRakelAction
): void
Sends a RawRakelAction to the Rakel radio.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
the RawRakelAction to be sent to the radio. |
Returns¶
void
Requires
Permissions RAKEL_RAW_COMMAND_SEND
Requires
Version Vehicle Services version 5.1.0 and above have full functionality. Other versions: function will throw an Error.
Settings Methods¶
onNewOrUpdatedSettings¶
onNewOrUpdatedSettings(callback
): void
Registers a callback to be run upon new application settings reception or settings update
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The callback to be executed. |
Returns¶
void
Requires
Version Vehicle Services version 5.0.0 and above have full functionality. Other versions: callback will never trigger.
Trigger
The callback triggers every time the settings are updated for this certified app, and when the certified app starts. Vehicle Services synchronizes these settings with Evam Central Services once every few hours.
System Methods¶
onNewOrUpdatedBattery¶
onNewOrUpdatedBattery(callback
): void
Used to assign a callback when the battery data is updated.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The callback with (optional) argument battery. Use this to access the battery. |
Returns¶
void
Requires
Permissions BATTERY_READ
Requires
Version Vehicle Services version 5.1.0 and above have full functionality. Other versions: callback will never trigger.
Trigger
The callback triggers every time the battery state is updated: charge, health, plugged status, or capacity. And when the certified app starts.
onNewOrUpdatedDeviceRole¶
onNewOrUpdatedDeviceRole(callback
): void
Registers a callback to be run upon new device role or device role update
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The callback to be executed. |
Returns¶
void
Requires
Permissions DEVICE_ROLE_READ
Requires
Version Vehicle Services version 5.0.0 and above have full functionality. Other versions: callback will never trigger.
Trigger
The callback triggers every time the device role is changed by the user through the Setup flow, and when the certified app starts.
onNewOrUpdatedDisplayMode¶
onNewOrUpdatedDisplayMode(callback
): void
Used to assign a callback when the display mode is updated.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The callback with (optional) argument display mode. Use this to access the display mode. |
Returns¶
void
Requires
Permissions DISPLAY_MODE_READ
Requires
Version Vehicle Services version 5.2.0 and above have full functionality. Other versions: callback will never trigger.
Trigger
The callback triggers every time the display mode is updated, either by the user or automatically based on the time of the day if the user chose to have to automatically updated.
onNewOrUpdatedInternetState¶
onNewOrUpdatedInternetState(callback
): void
Registers a callback to be run upon new internetState or internetState update
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The callback to be executed. |
Returns¶
void
Requires
Permissions CONNECTIVITY_READ
Requires
Version Vehicle Services version 5.1.0 and above have full functionality. Other versions: callback will never trigger.
Trigger
The callback triggers every time the state of the internet connectivity is updated, and when the certified app starts.
putAppInForeground¶
putAppInForeground(): void
Opens the app in foreground in Vehicle Services.
Returns¶
void
Requires
Permissions PUT_APP_IN_FOREGROUND
Requires
Version Vehicle Services version 5.2.2 and above have full functionality. Other versions: function will throw an Error.
Requires
Environment Evam device only
Telephony Methods¶
answerCall¶
answerCall(callId
): void
Answers a call that matches the given callId provided as part of the calls from newOrUpdatedCalls.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
the id of the call to answer. |
Returns¶
void
Requires
Permissions TELEPHONY
Requires
Version Vehicle Services version 5.2.4 and above have full functionality. Other versions: function will throw an Error.
Requires
Environment Evam device only
hangUpCall¶
hangUpCall(callId
): void
Hangs up or cancels a call that matches the given callId provided as part of the calls from newOrUpdatedCalls.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
the id of the call to be canceled. |
Returns¶
void
Requires
Permissions TELEPHONY
Requires
Version Vehicle Services version 5.2.4 and above have full functionality. Other versions: function will throw an Error.
Requires
Environment Evam device only
holdCall¶
holdCall(callId
): void
Puts a call on hold that matches the given callId provided as part of the calls from newOrUpdatedCalls.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
the id of the call to hold. |
Returns¶
void
Requires
Permissions TELEPHONY
Requires
Version Vehicle Services version 5.2.4 and above have full functionality. Other versions: function will throw an Error.
Requires
Environment Evam device only
makeCall¶
makeCall(number
): void
Initiates a new call to the given number.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
the phone number to call |
Returns¶
void
Requires
Permissions TELEPHONY
Requires
Version Vehicle Services version 5.2.4 and above have full functionality. Other versions: function will throw an Error.
Requires
Environment Evam device only
muteMicrophone¶
muteMicrophone(): void
Mutes the microphone of the device.
Returns¶
void
Requires
Permissions TELEPHONY
Requires
Version Vehicle Services version 5.2.4 and above have full functionality. Other versions: function will throw an Error.
Requires
Environment Evam device only
onNewOrUpdatedAudioDeviceTypes¶
onNewOrUpdatedAudioDeviceTypes(callback
): void
Used to assign a callback when the available and selected audio device types for phone calls are updated.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The callback with (optional) argument AudioDevices. Use this to access the current audio devices state. |
Returns¶
void
Requires
Permissions TELEPHONY
Requires
Version Vehicle Services version 5.3.1 and above have full functionality. Other versions: callback will never trigger.
Trigger
The callback triggers every time the available audio devices change or the selected audio device changes.
onNewOrUpdatedCalls¶
onNewOrUpdatedCalls(callback
): void
Used to assign a callback when the phone calls are updated.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The callback with (optional) argument array of PhoneCall. Use this to access the current phone calls. |
Returns¶
void
Requires
Permissions TELEPHONY
Requires
Version Vehicle Services version 5.2.4 and above have full functionality. Other versions: callback will never trigger.
Trigger
The callback triggers every time the state of incoming calls is updated: new incoming call, hangup etc.
onNewOrUpdatedMuteState¶
onNewOrUpdatedMuteState(callback
): void
Used to assign a callback when the device’s microphone mute state is updated.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The callback with (optional) argument boolean. Use this to access the current microphone mute state. |
Returns¶
void
Requires
Permissions TELEPHONY
Requires
Version Vehicle Services version 5.2.4 and above have full functionality. Other versions: callback will never trigger.
Trigger
The callback triggers every time the device’s microphone mute state is updated.
selectAudioDeviceType¶
selectAudioDeviceType(audioDeviceType
): void
Selects the audio device type for phone calls.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
the audio device type. |
Returns¶
void
Requires
Permission TELEPHONY
Requires
Version Vehicle Services version 5.3.1 and above have full functionality. Other versions: function will throw an Error.
Requires
Environment Evam device only
unholdCall¶
unholdCall(callId
): void
Resumes a call on hold that matches the given callId provided as part of the calls from newOrUpdatedCalls.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
the id of the call to be resumed. |
Returns¶
void
Requires
Permissions TELEPHONY
Requires
Version Vehicle Services version 5.2.4 and above have full functionality. Other versions: function will throw an Error.
Requires
Environment Evam device only
unmuteMicrophone¶
unmuteMicrophone(): void
Unmutes the microphone of the device.
Returns¶
void
Requires
Permissions TELEPHONY
Requires
Version Vehicle Services version 5.2.4 and above have full functionality. Other versions: function will throw an Error.
Requires
Environment Evam device only
Testing and Development Methods¶
injectAppId¶
injectAppId(appId
): void
Injects the certified app ID manually. This function is to be used for development only and will throw an error when used in Vehicle Services.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The app ID to be injected for development purposes. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectAppVersion¶
injectAppVersion(appVersion
): void
Injects the app version manually. This function is to be used for development only and will throw an error when used in Vehicle Services.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The app version to be injected for development purposes. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectAudioDevices¶
injectAudioDevices(audioDevices
): void
Injects the audio devices available (and selected). This function is to be used for development only and will throw an error when used in Vehicle Services.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
the audio devices to inject |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectAvailableVehicleStatusList¶
injectAvailableVehicleStatusList(vehicleStatusList
): void
Manually inject the Available Vehicle Status list to EvamApi (Only available in development.)
Parameters¶
Name |
Type |
Description |
---|---|---|
|
the list of available Vehicle Statuses |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectBattery¶
injectBattery(battery
): void
Injects the battery manually. This will trigger onNewOrUpdatedBattery(…)’s callback. This function is to be used for development only and will throw an error when used in Vehicle Services.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
The battery to be injected for development purposes. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectCalls¶
injectCalls(calls
): void
Inject a list of PhoneCall as they are sent from Vehicle Services. This function is to be used for development only and will throw an error when used in Vehicle Services.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
the calls to be injected. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectDeviceRole¶
injectDeviceRole(deviceRole
): void
Manually inject deviceRole to EvamApi (Only available in development.)
Parameters¶
Name |
Type |
Description |
---|---|---|
|
the deviceRole to inject. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectDisplayMode¶
injectDisplayMode(displayMode
): void
Injects the display mode manually. This will trigger onNewOrUpdatedDisplayMode(…)’s callback. This function is to be used for development only and will throw an error when used in Vehicle Services.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
The display mode (light or dark) to be injected for development purposes. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectInternetState¶
injectInternetState(internetState
): void
Manually inject internetState to EvamApi (Only available in development.)
Parameters¶
Name |
Type |
Description |
---|---|---|
|
the internetState to inject. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectLocation¶
injectLocation(location
): void
Manually inject location to EvamApi (Only available in development.)
Parameters¶
Name |
Type |
Description |
---|---|---|
|
the location to inject. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectMuteState¶
injectMuteState(isMuted
): void
Injects the mute state of the microphone. This function is to be used for development only and will throw an error when used in Vehicle Services.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
true if the microphone is muted. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectOSVersion¶
injectOSVersion(osVersion
): void
Injects the OS version manually. This function is to be used for development only and will throw an error when used in Vehicle Services.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The OS version to be injected for development purposes. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectOperation¶
injectOperation(activeCase
): void
Injects the Active Operation manually. This will trigger onNewOrUpdatedActiveOperation(…)’s callback. This function is to be used for development only and will throw an error when used in Vehicle Services.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
The active case to be injected for development purposes. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectOperationList¶
injectOperationList(operationList
): void
Injects the operation list manually. This will trigger onNewOrUpdatedOperationList(…)’s callback. This function is to be used for development only and will throw an error when used in Vehicle Services.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
The operation list to be injected for development purposes. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectRakelMessages¶
injectRakelMessages(rakelMessages
): void
Inject a list of raw Rakel messages as they would be received from the radio. This function is to be used for development only and will throw an error when used in Vehicle Services.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
list of raw Rakel messages. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectRakelState¶
injectRakelState(rakelState
): void
Manually inject the Rakel State to EvamApi (Only available in development.)
Parameters¶
Name |
Type |
Description |
---|---|---|
|
The Rakel State |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectSettings¶
injectSettings(settings
): void
Injects the settings manually. This will trigger onNewOrUpdatedSettings(…)’s callback. This function is to be used for development only and will throw an error when used in Vehicle Services.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The settings to be injected for development purposes. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectTrip¶
injectTrip(tripLocationHistory
): void
Manually inject tripLocationHistory to EvamApi (Only available in development.)
Parameters¶
Name |
Type |
Description |
---|---|---|
|
the tripLocationHistory to inject. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectVSVersion¶
injectVSVersion(vsVersion
): void
Injects the Vehicle Services platform version manually. This function is to be used for development only and will throw an error when used in Vehicle Services.
Parameters¶
Name |
Type |
Description |
---|---|---|
|
|
The Vehicle Services version to be injected for development purposes. |
Returns¶
void
Requires
Environment Development (in web browser) only.
injectVehicleState¶
injectVehicleState(vehicleState
): void
Manually inject vehicleState to EvamApi (Only available in development.)
Parameters¶
Name |
Type |
Description |
---|---|---|
|
the vehicleState to inject. |
Returns¶
void
Requires
Environment Development (in web browser) only.