Services

API Interface / iOS

Shared Instance

Use the shared instance as your interface to the MOVE SDK.

static let shared: MoveSDK

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: SDK must be in.readyMoveSDKState

func startAutomaticDetection() -> Bool

Returns 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.

Precondition: SDK must be in.runningMoveSDKState.

func stopAutomaticDetection() -> Bool

Returns false if the SDK is not in .ready 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.

Precondition: SDK must be in.running MoveSDKState.

func forceTripRecognition()

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.

func startTrip(metadata: [String: String] = [:]) -> Bool

Returns 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 or backgroundLocationPermissionMandatorywith this API, as they will be ignored.

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.

func 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.

func 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.

func setTripStartListener(_ listener: @escaping MoveTripStartCallback)

Processing Services

Get SDK State

Gets the current MoveSDKState.

func getSDKState() -> MoveSDKState

Return
MoveSDKState	Latest SDK State

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.ready.

func setSDKStateListener(_ listener: SDKStateCallback)

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

Get Trip State

Gets the current MoveTripState.

func getTripState() -> MoveTripState

Return
MoveTripState	Current MoveTripState

Set Trip State Listener

Provide a block to be invoked every time MoveTripState changes.

func setTripStateListener(_ listener: TripStateCallback)

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

Get Device Status

Gets the current MoveDeviceStatus.

func getDeviceStatus() -> MoveDeviceStatus

Return
MoveDeviceStatus	Current MoveDeviceStatus

Get Service Failures

Gets the current MoveServiceFailures.

func getServiceFailures() -> [MoveServiceFailure]

Return
List of MoveServiceFailure	A list of failed services.

Set Service Failure Listener

func setServiceFailureListener(_ listener: @escaping MoveServiceFailureCallback)

Provide a block to be invoked every time MoveServiceFailures change.

Callback
MoveServiceFailureCallback	Block that gets invoked when service failure state changes.

Get Service Warnings

Gets the current MoveServiceWarnings.

func getServiceWarnings() -> [MoveServiceWarning]

Return
List of MoveServiceWarnings.	A list of partially working services.

Set Service Warning Listener

Provide a block to be invoked every time MoveServiceWarnings change.

func setServiceWarningListener(_ listener: @escaping MoveServiceWarningCallback)

Callback
MoveServiceWarningCallback	Block that gets invoked when service warnings change.

Set Metadata Listener

Provide a block returning bundle of 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. This metadata will be forwarded back along with the trip when fetched by the client-server, so the host app can utilize it in its app. Note: The SDK will not use this metadata element in any way, it is just passed through to the project environment.

The block provides the trip's start and stop times. Make sure to only include metadata events that are relevant for the given start and end periods.

func setTripMetaDataListener(_ listener: MetaDataCallback)

Callback
MetaDataCallback	Block that gets invoked on every trip finish. The block provides the trip's start and stop times.

Usage Example

MoveSDK.shared.setMetadataListener{ (tripStartTime, tripEndTime) in
    getCollectedMetadataForPeriod(start: tripStartTime, end: tripEndTime)
}

Set Log Listener

Provide a block to be invoked every time a new SDK log event occurs.

func setLogListener(_ listener: LogCallback)

Set Console Logging State

Toggles console logging enabled state.

This doesn't affect recieving the logs via setLogListener(_ listener: MoveLogCallback) API.

Enabled by default.

func setConsoleLogging(enabled: Bool) 

Parameter
enabled	Boolean that sets SDK console logging to enabled or not.

Geocoding

Geo-coordinate address lookup.

func geocode(latitude: Double, longitude: Double, completion: @escaping (Result<String, MoveGeocodeError>) -> Void)

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

Geocode will use Apple's builtin CLGeocoder.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.

CLGeocoder.reverseGeocodeLocation has its own throttling and maybe used up for the app calling this function.

Delete Local Data

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

Precondition: MoveSDKState should be initialized.

func deleteLocalData()

Synchronize User Data

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

func synchronizeUserData()

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

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.

func setLiveLocationTag(_ tag: String?) -> Bool

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.

func initiateAssistanceCall(_ completionHandler: @escaping (MoveAssistanceCallStatus) -> Void)

Parameters
completionHandler	A callback returning a MoveAssistanceCallStatus.

The application should process the callback status and inform the user in case of failure.

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

New feature in MOVE SDK 2.1

func setAssistanceMetaData(_ metadata: String)

Parameters
metadata	A string to be sent with each assistance call or impact

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

Get Device Qualifier

New feature in MOVE SDK 2.2

Get a unique qualifier to identify the individual device.

func getDeviceQualifier() -> String

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

Device Discovery

Device discovery for iBeacon and Audio devices. Multiple devices can be registered but limitations of CLLocationManager region API may apply.

From the start of a trip registered devices are scanned after a period deviceDetectionDelay, beacons are scanned for a duration deviceDetectionDuration repeated after an interval deviceDetectionInterval, see MoveOptions.

If stopScanOnFirstDiscovered is set the scan stops after any device is discovered.

Device scanning results are appended to the trip metadata.

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

Register Device

Register an additional device:

func register(devices: [MoveDevice])

Unregister Device

Unregister a device:

func unregister(devices: [MoveDevice])

All devices are unregistered after shutdown.

Get Registered Devices

Get current registered devices.

func getRegisteredDevices() -> [MoveDevice]

Set Device Discovery Listener

Set a device discovery listener to be fired when registered MoveDevices are scanned. It returns a list of the devices registered with register(devices: [MoveDevice]). If the option stopScanOnFirstDiscovered is set the list may be incomplete.

func setDeviceDiscoveryListener(_ listener: @escaping MoveDeviceDiscoveryCallback)

Callback
MoveDeviceDiscoveryCallback	Block that gets invoked whenever a scan for registered devices completes.

Set MoveDevice Connection State Listener

Since MOVE SDK v2.10.0

Set a MoveDevice connection state listener to be fired when the connection state of a previously registered MoveDevice has changed. Only works with paired audio devices, not iBeacons.

func setDeviceStateListener(_ listener: @escaping MoveDeviceStateCallback)

Parameters
MoveDeviceStateCallback	A callback returning the MoveDevice which connection state was changed.

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.

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

func setRemoteConfigChangeListener(_ listener: @escaping MoveRemoteConfigChangeCallback)

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