Services

API Interface / React Native

import MoveSdk from 'react-native-move-sdk';

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.

MoveSdk.startAutomaticDetection(): Promise<boolean>

Promise will be resolved with false if the SDK is not in .ready state.

Stop Automatic Detection

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

MoveSdk.stopAutomaticDetection(): Promise<boolean>

Promise will be resolved with false if the SDK is not in .running state.

Force Trip Recognition

Temporarily calibrates the SDK to the highest detection mode.

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

The 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 SDK is on the highest detection state to detect the trip faster.

MoveSdk.forceTripRecognition(): void

Finish Current Trip

Ends the current ongoing trip.

This API will end the ongoing trip and set MoveTripState back to .idle. The SDK is responsible for detecting the trip start and end points. The 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.

MoveSdk.finishCurrentTrip(): void

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.

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.

MoveSdk.ignoreCurrentTrip(): void

Set Trip Metadata

Since MOVE SDK v2.8.0

Add key-value pairs to be appended to the trip metadata before the trip finishes.

Host apps can use this API to add any app-level information (for ex. Bluetooth beacon detected, foreground/background time, etc) to append to a trip as metadata (only for current trip, when the next trip starts old metadata is removed). This metadata will be forwarded back along with the trip when fetched by the client-server. Note: The SDK will not use this metadata element in any way, it is just passed through to the project environment.

MoveSdk.setTripMetadata(metadata?: { [key: string]: string }): void

Manual Start Trip

Since MOVE SDK v2.8.0

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.

startTrip(metadata?: { [key: string]: string} ): Promise<boolean>

Promise will be resolved with false if the SDK is not in .ready state.

Precondition: MOVE SDK must be inREADYMoveSdkState.

Manually starting a trip bypasses additional trip detection checks. Manually started trips must be ended with finishCurrentTrip()

It is recommended not to use MoveOptions motionPermissionMandatory orbackgroundLocationPermissionMandatorywith this API, as they will be ignored.

Processing Services

Keep in foreground (Android only)

When an Android application is in the background it may receive limited data (location, sensors, etc.). To improve this behaviour, 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.

MoveSdk.keepInForeground(enabled: boolean): void

Keep active (Android only)

To save battery consumption, the SDK is using several triggers to start its data listeners. In case of trouble, these triggers can be circumvented by allowing the MoveSdk to stay active all the time. In that case the 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.

MoveSdk.keepActive(enabled: boolean): void

Get SDK State

Gets the current MoveSDKState.

MoveSdk.getState(): Promise<SdkState>

Get Trip State

Get the current MoveTripState.

MoveSdk.getTripState(): Promise<TripState>

Get Auth State

Get the current MoveAuthState.

MoveSdk.getAuthState(): Promise<AuthState>

Get Errors

Get the current list of MoveServiceFailure.

MoveSdk.getErrors(): Promise<ErrorListType>

Get Warnings

Get the current list of MoveServiceFailure.

MoveSdk.getWarnings(): Promise<WarningListType>

Set SDK State Listener

Provide a block to be invoked every time MoveSDKState changes.

Set the MoveSDKState listener before initializing the SDK to anticipate the SDK State changes triggered by the initialization API. Here the host app can start the SDK services when MoveSDKState is.readyor handle errors if occurred.

For android platform it is necessary to start listen explicitly by calling:

if (Platform.OS === 'android') {
    MoveSdk.startNativeSdkStateListener();
}

MoveSdk.addSdkStateListener(sdkStateChanged: (state: SdkState) => void): ListenerSubscription;

Callback
sdkStateChanged	Block that gets invoked every time MoveSDKState is changed and provides the updated MoveSDKState.

Set SDK Auth State Listener

Provide a block to be invoked every time MoveAuthState changes.

MoveSdk.addAuthStateListener(authStateChanged: (event: AuthStateEvent) => void): ListenerSubscription;

Callback
authStateChanged	Block that gets invoked every time MoveAuthState is updated.

Authentication Expiry

The host app is expected to monitor MoveAuthState updates viaauthStateUpdateListene API and handle those changes accordingly.

Check Authentication updates and expiry for more details about authentication expiry and renewal.

Set Trip State Listener

Provide a block to be invoked every time MoveTripState changes.

MoveSdk.addTripStateListener(tripStateChanged: (state: TripState) => void): ListenerSubscription;

Callback
tripStateChanged	Block that gets invoked every time MoveTripState is changed and provides the updated MoveTripState.

Set Errors Listener

Provide a block to be invoked every time MoveServiceFailure changes.

MoveSdk.addErrorsListener(errorsReceived: (errors: ErrorListType) => void): ListenerSubscription;

Set Warnings Listener

Provide a block to be invoked every time MoveServiceWarning changes.

MoveSdk.addWarningsListener(warningsReceived: (warnings: ErrorListType) => void): ListenerSubscription;

Set Log Listener

Add a log listener for debugging.

static addLogListener(logReceived: (event: MoveSdkLog) => void): ListenerSubscription;

Shutdown SDK

Shutdown SDK shared instance.

Precondition: SDK must be initialized.

Stops SDK services, send the queued user data, and de-initializes the SDK. After that is executed, the MoveSDKState will transit to .uninitialized.

If it's necessary just to stop all SDK services you most likely need to use stopAutomaticDetection instead of shutdown. Use shutdown in case of user's logout, SDK auth error (in those cases where you know for sure that you will need to execute MoveSdk.setup with new MoveAuth object, for example).

MoveSdk.shutdown(force:boolean = true): Promise<ShutdownReturnType>

Parameters	Default
force	true	If true, shutdown executes immediately. Pending Data may be lost and always returns with a success, see ShutdownReturnType otherwise.

When force: false is specified the shutdown may fail when pending data cannot be uploaded and reject the promise (status code: NETWORK_ERROR) which needs to be handled.

Resolve Error

MoveSdk.resolveError(): void

Synchronize User Data

Used to force synchronizing user data with the SDK server. Limited to once per 2 minutes.

MoveSdk.synchronizeUserData(): void

Other Services

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.

MoveSdk.initiateAssistanceCall(): Promise<boolean>

Returns a promise with a MoveAssistanceCallStatus.

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

Set Assistance MetaData

Since MOVE SDK 2.1.0

MoveSdk.setAssistanceMetaData(data: string): void

Parameters
data	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.

Set Timer (Android only)

Since MOVE SDK v2.7.0

MoveSdk.setTimer(callback: () => void, delay?: number): string

Usual setTimeout doesn't work if app is in the background on Android. The SDK provides setTimer that works in the same way as setTimeout, but also in the background. A call to setTimer returns a “timer identifier” that we can use to cancel the execution via cancelTimer.

Parameters	Default
delay	60000	number	Delay in miliseconds.
callback		function	Callback that will be executed after delay.

Cancel Timer (Android only)

Since MOVE SDK 2.7.0

MoveSdk.cancelTimer(key: string): void

This method removes timer that was added via setTimer.

Parameters
key	string	"Timer identifier" which was returned from setTimer.

Live Location TAG

Since MOVE SDK 2.8.0

MoveSdk.setLiveLocationTag(tag?: string): Promise<boolean>

Adds a Tag to trip events. This Tag information is added to the timeline data. To clear the Tag do not pass parameter.

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

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 (no parameter is passed).
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].

Configuration services

Update authentication

Updates SDK MoveAuth. On SDK auth expiry, the authStateListener will trigger expired state. The host app is expected to fetch a new MoveAuth using its project API key and pass it to the MoveSDK using the following API:

MoveSdk.updateAuth(auth: MoveSdkAuth): Promise<void>

Parameters
auth	The user's updated Auth object with the new token.

Update config

Since MOVE SDK v2.8.0

Change the MoveConfig originally passed in setup. Optionally update the MoveOptions passed in setup.

MoveSdk.updateConfig(config: MoveSdkConfig, options?: MoveSdkOptions): Promise<boolean>

Device Discovery

Due to limitations in Android’s Classic Bluetooth APIs, reliable connection status tracking may not always be possible. For more details and available workarounds, see Forcing the Signal - Classic Bluetooth.

Start Scanning Devices

Start scanning for devices which can be registered on the SDK for trip device discovery. A block will get invoked each time new devices are found.

MoveSdk.startScanningDevices(sdkDevicesDetected: (state: Array<MoveSdkDevice>) => void, filter: MoveSdkDeviceFilter[], uuid?: string, manufacturerId?: number): ListenerSubscription;

Parameters
sdkDevicesDetected	Listener	Block that gets invoked every time a new MoveSdkDevice is detected.
filter	MoveSdkDeviceFilter	Filter devices by type. See bellow.
uuid	string	UUID String required to scan beacons.
manufacturerId	number	Manufacturer ID needed to scan beacons.

Returns a subscription object. Scanning will stop automatically when the subscription is removed, otherwise the scan will continue and this will impact device battery usage.

A list of filters can be specified to filter which devices to scan for:

MoveDeviceFilter
paired	Scan for paired devices. Default
connected	Scan for connected devices. New since version 2.10.4.
beacon	Scan for beacon devices. uuid and manufacturerId required.

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.

MoveSdk.addDeviceStateListener(onScanResult: (results: Array<MoveSdkDevice>) => void): ListenerSubscription;

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

Get Registered Devices

Get a list of devices (MoveSdkDevice) registered to be discovered during trips.

MoveSdk.getRegisteredDevices(): Promise<Array<MoveSdkDevice>>;

Register Devices

Register devices (MoveSdkDevice) to be discovered during trips.

MoveSdk.registerDevices(devices: Array<MoveSdkDevice>): Promise<boolean>;

Unregister Devices

Unregister devices (MoveSdkDevice) to be discovered during trips.

MoveSdk.unregisterDevices(devices: Array<MoveSdkDevice>): Promise<boolean>;

Since MOVE SDK v2.13: Devices are persisted after shutdown.

Discover Devices

MoveSdk.addDeviceDiscoveryListener(onScanResult: (results: Array<MoveScanResult>) => void): ListenerSubscription;

Subscribe to updates for registered devices scanned during trips. See MoveScanResult.

Set Health Score Listener

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

MoveSdk.addHealthListener(scoreReceived: (health: MoveHealthScore) => void): ListenerSubscription

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

Set Remote Config Change Listener

Since MOVE SDK v2.5

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

MoveSdk.addRemoteConfigChangeListener(configChangeReceived: (config: Array<IssueListService>) => void): ListenerSubscription

Parameters
listener	A callback returning a List of services after a successful server fetch.