Services

API Interface / Android

Update Config

Change the config originally passed in setup.

fun updateConfig(config: MoveConfig, options: MoveOptions? = null)

Parameters
config	MoveConfig	Move services configuration.
options	MoveOptions	Optional MoveOptions if they need to be changed.

Occasionally this functionality is needed for deployed apps when a projects configuration is updated on the backend.

Detection Services

Start Automatic Detection

Starts the required detection services stated in the MoveConfig passed on initialization. Starting the service will set the MoveSdkState to Running.

Precondition: MOVE SDK must be inREADYMoveSdkState.

fun startAutomaticDetection()

Stop Automatic Detection

Stops the automatic detection service, including all MOVE SDK services like driving detection, points of interest, walking and places. Stopping the service will set the MoveSdkState back to Ready.

Precondition: MOVE SDK must be inRunningMoveSdkState.

fun stopAutomaticDetection()

Trip Services

Force Trip Recognition

Temporarily calibrates the MOVE SDK to the highest detection mode.

In order to optimize battery consumption, the MOVE SDK goes through different detection modes with different battery consumption levels, depending on the user's current behavior and activity. In general, the MOVE SDK is responsible for alternating between those different detection modes.

The MOVE SDK also provides hosting apps this API to call if they have their own reasons (like buttons, sensors or beacons) to believe that the user is starting a trip. This will make sure the MOVE SDK is on the highest detection state to detect the trip faster.

Precondition: SDK must be inRUNNING MoveSdkState.

fun forceTripRecognition()
fun forceTripRecognition(duration: Long) 

Parameters	Type
duration	Long	Limit the high power detection to a certain amount of time in milliseconds, to not drain the battery. Default one minute (60 000ms)

Manual Start Trip

Manually force the start of a trip, bypassing trip validation checks. This non-standard SDK usage may be feasible only in situations where active user input can be expected. Using the metadata parameter, self-defined information can be added to each trip which can be fetched from the timeline.

fun startTrip(metadata: Map<String, String>?)

Be sure that you set the start flag to false during the MOVE SDK setup.

e.g.: setup( auth = moveAuth, config = moveConfig, start = false )

Precondition: MOVE SDK must be in.readyMoveSdkState.

Manually starting a trip bypasses additional trip detection checks. It is strongly recommended to finish manually started trips with finishCurrentTrip()

Starting a trip with startTrip(...) prevents the execution of startAutomaticDetection().

Finish Current Trip

Ends the current ongoing trip.

This API will end the ongoing trip and set MoveTripState back to .idle. The MOVE SDK is responsible for detecting the trip start and end points. The MOVE SDK also provides hosting apps this API to call if they have their own reasons (like sensors or beacons) to believe that the user's trip has ended.

Precondition: MoveTripState should be in an active trip.

fun finishCurrentTrip()

If this API is called while the user is active on a driving trip, a new trip will start again right away. If the intention is to un-track the ongoing trip, call ignoreCurrentTripAPI.

More information about trip states can be found in MoveTripState.

If the trip was started with startTrip(metadata:)finishCurrentTrip() brings the SDK back to .ready state.

Ignore Current Trip

Ignores the current ongoing trip.

This API will set the ongoing MoveTripState to .ignored. Data of ignored trips is purged and not sent to the server.

Precondition: MoveTripState should be in an active trip.

fun ignoreCurrentTrip()

Set Trip Start Listener

Provides a block to be invoked when a trip actually begins.

In comparison to the tripStateListener (only state changes) the tripStartListener will provide you with the start time of the actual trip.

fun setTripStartListener(listener: TripStartListener)

Processing Services

Keep in foreground

When an Android application is in the background it may receive limited data (location, sensors, etc.). To improve this behavior, it is possible to put the application always in the foreground with a visible notification that cannot be discarded. Just because it's visible it doesn't mean that it is performing any data collection at all. So this should not have any significant battery impact at all.

Disabled by default.

Since it may be annoying to the user, it should only be enabled in case of problems.

fun keepInForeground(enabled: Boolean)

Keep active

To save battery consumption, the MOVE SDK is using several triggers to start its data listeners. In case of trouble, these triggers can be circumvented by allowing the MOVE SDK to stay active all the time. In that case the MOVE SDK is always monitoring required data and is therefore consuming more battery. Depending on the configuration, it may happen that the notification (see notification handling) is always visible to the user.

Disabled by default.

Since this is consuming more battery, it should only be enabled in case of problems.

fun keepActive(enabled: Boolean)

Console logging

Toggles whether the MOVE SDK is allowed to log into the console or not.

Enabled by default.

fun consoleLogging(enabled: Boolean)

Parameters
enabled	Boolean that sets MOVE SDK console logging to enabled or not.

Mock locations

In Android it is possible to use simulated location by enabling it in the device developer mode. If you want the MOVE SDK to support those locations, you need to specify it. By default this is disabled to prevent wrong data.

Points of Interests are not supported with mock locations. Keep in mind that mock locations may have negative impact on trip recognition afterwards.

Rooted devices are still able to send mock locations without allowing mock locations.

.allowMockLocations(allow: Boolean)

Parameters
allow	Allows driving with mock locations. Should only be used in debug/test builds

Get MOVE SDK State

Gets the current MoveSdkState.

fun getSDKState() : MoveSDKState

Return
MoveSdkState	Latest MoveSdkState.

Get Trip State

Gets the current MoveTripState.

fun getTripState(): MoveTripState

Return
MoveTripState	Latest MoveTripState.

Get Device Status

Gets the current MoveDeviceStatus.

fun getDeviceStatus(): MoveDeviceStatus

Return
MoveDeviceStatus	Latest MoveDeviceStatus.

Get Service Failures

Gets the current MoveServiceFailures.

func getServiceErrors(): List<MoveServiceFailure>

Return
List of MoveServiceFailure	A list of failed services.

Set Service Error Listener

func setServiceErrorListener(listener: MoveErrorListener)

Provide a block to be invoked every time MoveServiceFailures will change.

Parameters
MoveErrorListener	Block that gets invoked when service failure state changes.

Get Service Warnings

Gets the current MoveServiceWarnings.

func getServiceWarnings(): List<MoveServiceWarning>

Return
List of MoveServiceWarnings	A list of partially working services.

Set Service Warning Listener

Provide a block to be invoked every time MoveServiceWarnings will change.

fun setServiceWarningListener(listener: MoveWarningListener)

Listener
MoveWarningListener	Block that gets invoked when service warnings change.

Delete Local Data

Deletes all the collected user MOVE SDK data stored on the device. This doesn't affect the MoveSdkState.

Precondition: MOVE SDK must be initialized.

fun deleteLocalData()

Shutdown SDK

Shutdown SDK shared instance.

Stops SDK services, send the queued user data, and de-initializes the MOVE SDK. After .shutdown() is executed, the MoveSdkState will transit to Uninitialised.

Precondition: MOVE SDK must be initialized.

fun shutdown(force: Boolean = true, callback: ((MoveShutdownResult) -> Unit)? = null)

Parameters	Default
force	true	If true, shutdown executes immediately. Pending Data may be lost.
callback	null	Returns a MoveShutdownResult upon completion. May fail if not forced.

Set Health Score Listener

Provide a block to be invoked every time MoveHealthScore will change.

fun setMoveHealthScoreListener(listener MoveHealthScoreListener)

Parameters
MoveHealthScoreListener	Block that get's invoked when the health score changes.

Geocoding

Geo-coordinate address lookup.

fun geocode(latitude: Double, longitude: Double, result: (GeocodeResult) -> Unit)

Parameters
latitude	Geo-coordinate latitude
longitude	Geo-coordinate longitude
completion	Callback that returns a Result with an address String or a MoveGeocodeError

Geocode will try a reverseGeocodeLocation or fallback to contacting the MOVE backend to attempt a geo-lookup.

Throttle: Geocode is limited to a maximum of 100 lookups per hour.

Delete Local Data

Deletes all the collected user MOVE SDK data stored on the device. This doesn't affect the MoveSDKState.

Precondition: MoveSDKState should be initialized.

fun deleteLocalData()

Synchronize User Data

Used to force synchronizing user data with the MOVE backend. Limited to once per 2 minutes.

fun synchronizeUserData(result: ((Boolean) -> Unit)?)

The result Returns FALSE in case there are Timeline-relevant packages in the queue that remain to be sent to the MOVE backend; and it returns TRUE in case the queue is empty.

Parameters
result	Optional callback to retrieve result

Other services

Live Location TAG

New feature since MOVE SDK 2.8.0

Adds a Tag (=string value) to trip events. This Tag information is added to the timeline data.

To clear the Tag pass null as parameter.

After a shutdown(...) (Android / iOS) the Tag is also cleared.

fun setLiveLocationTag(tag: String?): Boolean

Parameters
tag	String [a-z] [0-9] and null to clear the Tag.

Return values
true	Live Location Tag is applied.
true	Live Location Tag is cleared. (parameter null)
false	Live Location Tag exceeds the limit of 200 characters.
false	Live Location Tag is blank or empty.
false	If the passed chars are not one of these [a-z] [0-9].

Initiate Assistance Call

New feature in MOVE SDK 2.x; configuration in MOVE dashboard pending - please get in touch.

Initiate an assistance call to emergency services.

Precondition: The assistance call service needs to be configured. The MOVE SDK needs to be in ready or running state.

fun initiateAssistanceCall(assistanceListener: AssistanceStateListener)

Parameters
assistanceListener	A callback returning a MoveAssistanceCallStatus.

Set Assistance MetaData

New feature since MOVE SDK 2.1.

fun setAssistanceMetaData(assistanceMetadataValue: String?)

Before SDK 2.4 Android returns null.

Get a unique qualifier to identify the individual device.

Parameters
assistanceMetadataValue	String	A string to be sent with each assistance call or impact.

The metadata string is set once, and then sent to the server with each and every manual assistance call and with AID report. The contents of the string can be anything, e.g. JSON data. The assistance data is persisted once set.

Get Device Qualifier

Get a unique qualifier to identify the individual device. For Android returns null

fun getDeviceQualifier(): String?

The device qualifier should be passed to the backend during user registration. See Move backend.

Device Discovery

Device discovery for Bluetooth devices. Multiple devices can be registered.

The configuration of the scanning will be done with the object DeviceDiscovery in MoveOptions during MOVE SDK setup. From the start of a trip registered devices are scanned after a startDelay and are scanned for duration. This scan will repeat after an interval.

To scan for Bluetooth devices only once then the flag stopScanOnFirstDiscovered should be set.

Device scanning results are appended to the trip metadata.

Registering/unregistering devices during a trip may result in undefined behavior.

Before the DeviceDiscovery configuration can be changed, a shutdown with a following setup must be executed.

Set Device Discovery Listener

Set a device discovery listener to be fired when registered MoveDevice's are scanned.

If stopScanOnFirstDiscovered of the DeviceDiscovery object is set to true then the list of MoveScanResults may be incomplete.

fun deviceDiscoveryListener(listener: DeviceDiscoveryListener)

Parameters
listener -> DeviceDiscoveryListener	A callback returning a MoveScanResult.

Set MoveDevice Connection State Listener

Since MOVE SDK v2.10.0

Set a MoveDevice connection state listener to be fired when the Bluetooth connection state of a previously registered MoveDevice has changed.

fun setDeviceStateListener(listener: MoveDeviceStateListener?)

Parameters
listener -> MoveDeviceStateListener	A callback returning the MoveDevice which connection state was changed.

Register Device

Please note that MoveDevices can only be registered if the SDK has been configured with .setup()

Register MoveDevice's / add more MoveDevice's:

fun registerDevices(devices: List<MoveDevice>)

Parameters
devices	A list of MoveDevice's to be scanned during a trip.

Unregister Device

Unregister a MoveDevice:

fun unregisterDevices(devices: List<MoveDevice>)

All devices are unregistered after shutdown.

Parameters
devices	A list of MoveDevice's that should no longer be scanned during a trip.

Get Registered Devices

Get current registered MoveDevice's.

suspend fun getRegisteredDevices(): List<MoveDevice>

Alternative it is possible to subscribe to registered devices changes.

fun getRegisteredDevicesFlow(): Flow<List<MoveDevice>>

Additional device discovery methods

fun convertToMoveDevice(scanResult: ScanResult): MoveDevice

Converts android.bluetooth.le.ScanResult into a MOVE SDK specific MoveDevice.

fun convertToMoveDevice(bluetoothDevice: BluetoothDevice): MoveDevice

Converts android.bluetooth.BluetoothDevice into a MOVE SDK specific MoveDevice.

Configuration services

Update authentication

Deprecated: Token expiry is no longer a valid auth state forwarded to the app and does not need to be handled.

Updates MOVE SDK MoveAuth. The host app was expected to fetch a new MoveAuth using its project API key and pass it to the MoveSDK using the following API:

@Deprecated("Do not use manual token update, this will be handled internally by the Move SDK")
fun updateAuth(auth: MoveSdk.Auth, onError: (MoveAuthError) -> Unit)

Set Remote Config Change Listener

Since MOVE SDK v2.5

Provides a block to be invoked every time MoveConfig was successfully fetched from the server.

If the MoveConfig object couldn't be fetched from the server then a MoveConfigurationError ServiceUnreachable will be triggered.

fun setRemoteConfigChangeListener(listener: RemoteConfigChangeListener)

Parameters
listener	A callback returning a MoveConfig object after a successful server fetch.