Dolphin MOVE SDK
2.x
2.x
  • Introduction
  • MOVE Services
  • MOVE SDK
    • Getting Started
      • MOVE Dashboard
        • Access Control
        • Configuration
        • Timeline
        • Points of Interest
      • Android
        • Installation
        • Quick Start
      • iOS
        • Installation
        • Quick Start
        • Troubleshooting
      • React Native
      • Flutter
      • Move SDK CLI
    • API Interface
      • Android
        • Initialization
        • Services
      • iOS
        • Initialization
        • Setup
        • Services
      • React Native
        • Components
        • Initialization
        • Services
      • Flutter
        • Initialization
        • Services
    • Models
      • Listeners/Callbacks
      • MoveAssistanceCallStatus
      • MoveAuth
      • MoveAuthError
      • MoveAuthResult
      • MoveAuthState
      • MoveConfig
      • MoveConfigurationError
      • MoveDevice
      • MoveDeviceStatus
      • MoveGeocodeError
      • MoveHealthItem
      • MoveHealthScore
      • MoveOptions
        • DeviceDiscovery
      • MoveSdkState
      • MoveSdkAndroidConfig
      • MoveTripState
      • MoveScanResult
      • MoveServiceFailure
      • MoveServiceWarning
      • MoveShutdownResult
    • Appendix
      • Token refresh
      • Android
        • Permission Handling
          • Permission Overview
          • Runtime Permissions
        • Battery optimization
        • Notification Management
      • iOS
        • Permissions Handling
        • App Store
      • React Native
        • Permission Handling
  • MOVE Backend
    • MOVE Backend
      • MOVE Admin API
      • MOVE TIMELINE API
      • MOVE State API
      • MOVE Last Location API
    • MOVE Generic Notifier
    • MOVE Assistance Notifier
    • Example requests
  • FAQ
  • Changelog
    • Android
    • iOS
    • React
    • Flutter
    • Backend
  • Data privacy (GDPR)
Powered by GitBook
On this page
  • Detection Services
  • Start Automatic Detection
  • Stop Automatic Detection
  • Force Trip Recognition
  • Manual Start Trip
  • Finish Current Trip
  • Ignore Current Trip
  • Set Trip Start Listener
  • Processing Services
  • Get SDK State
  • Set SDK State Listener
  • Get Trip State
  • Set Trip State Listener
  • Get Device Status
  • Get Service Failures
  • Set Service Failure Listener
  • Get Service Warnings
  • Set Service Warning Listener
  • Set Metadata Listener
  • Set Log Listener
  • Set Console Logging State
  • Set Health Score Listener
  • Geocoding
  • Delete Local Data
  • Synchronize User Data
  • Other Services
  • Live Location TAG
  • Initiate Assistance Call
  • Set Assistance MetaData
  • Get Device Qualifier
  • Device Discovery
  • Register Device
  • Unregister Device
  • Get Registered Devices
  • Set Device Discovery Listener
  • Set MoveDevice Connection State Listener
  • Set Remote Config Change Listener
  1. MOVE SDK
  2. API Interface
  3. iOS

Services

API Interface / iOS

PreviousSetupNextReact Native

Last updated 8 months ago

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 passed on initialization. Starting the service will set the to .running.

Precondition: SDK must be in.ready

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

Precondition: SDK must be in.running.

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.

func forceTripRecognition()

Manual Start Trip

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

Returns false if the SDK is not in .ready state.

Finish Current Trip

Ends the current ongoing 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.

Ignore Current Trip

Ignores the current ongoing 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

func getSDKState() -> MoveSDKState

Return

Latest SDK State

Set SDK State Listener

func setSDKStateListener(_ listener: SDKStateCallback)

Callback

Get Trip State

func getTripState() -> MoveTripState

Return

Set Trip State Listener

func setTripStateListener(_ listener: TripStateCallback)

Callback

Get Device Status

func getDeviceStatus() -> MoveDeviceStatus

Return

Get Service Failures

func getServiceFailures() -> [MoveServiceFailure]

Return

A list of failed services.

Set Service Failure Listener

func setServiceFailureListener(_ listener: @escaping MoveServiceFailureCallback)

Callback

Block that gets invoked when service failure state changes.

Get Service Warnings

func getServiceWarnings() -> [MoveServiceWarning]

Return

A list of partially working services.

Set Service Warning Listener

func setServiceWarningListener(_ listener: @escaping MoveServiceWarningCallback)

Callback

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

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.

Set Health Score Listener

func setHealthScoreListener(_ listener: @escaping MoveHealthScoreCallback)

Parameter

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

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

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

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.

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

Initiate an assistance call to emergency services.

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

Parameters

completionHandler

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

Device Discovery

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

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])

Get Registered Devices

Get current registered devices.

func getRegisteredDevices() -> [MoveDevice]

Set Device Discovery Listener

func setDeviceDiscoveryListener(_ listener: @escaping MoveDeviceDiscoveryCallback)

Callback

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

Set MoveDevice Connection State Listener

Since MOVE SDK v2.10.0

func setDeviceStateListener(_ listener: @escaping MoveDeviceStateCallback)

Parameters

Set Remote Config Change Listener

Since MOVE SDK v2.5

func setRemoteConfigChangeListener(_ listener: @escaping MoveRemoteConfigChangeCallback)

Parameters

listener

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

Precondition: SDK must be in.running .

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 .

Precondition: MOVE SDK must be inREADY.

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

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

This API will end the ongoing trip and set 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: should be in an active trip.

More information about trip states can be found in .

If the trip was started with finishCurrentTrip() brings the SDK back to READY state.

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

Precondition: should be in an active trip.

Gets the current.

Provide a block to be invoked every time changes.

Set the listener before initializing the SDK to anticipate the SDK changes triggered by the initialization API. Here the host app can start the SDK services when is.ready.

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

Gets the current .

Current

Provide a block to be invoked every time changes.

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

Gets the current .

Current

Gets the current .

List of

Provide a block to be invoked every time change.

Gets the current .

List of .

Provide a block to be invoked every time change.

Callback that returns a Result with an address String or a

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

Precondition: should be initialized.

After a shutdown(...) ( / ) the tag is also cleared.

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

A callback returning a .

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

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 .

All devices are unregistered after .

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

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

A callback returning the which connection state was changed.

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

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

MoveConfig
MoveSDKState
MoveSDKState
MoveSDKState
MoveSDKState
MoveSDKState
MoveSdkState
MoveTripState
MoveTripState
MoveTripState
MoveTripState
MoveTripState
MoveSDKState
MoveSDKState
MoveSDKState
State
MoveSDKState
MoveTripState
MoveTripState
MoveDeviceStatus
MoveSDKState
MoveSDKState
get in touch
finishCurrentTrip()
startTrip(metadata:)
MoveSDKState
MoveSDKState
MoveSDKState
MoveTripState
MoveTripState
MoveTripState
MoveTripState
MoveDeviceStatus
MoveDeviceStatus
MoveDevice
MoveDevice
iOS
MoveServiceWarnings
MoveServiceWarnings
MoveServiceWarnings
MoveServiceFailures
MoveServiceFailures
MoveServiceFailure
MoveOptions
MoveOptions
timeline
shutdown
MoveDevice
Android
MoveConfigurationError
Move backend
MoveDevice
stopScanOnFirstDiscovered
MoveConfig
MoveGeocodeError
MoveAssistanceCallStatus
SDKStateCallback
TripStateCallback
MoveServiceFailureCallback
MoveServiceWarningCallback
MetaDataCallback
MoveHealthScoreCallback
MoveDeviceDiscoveryCallback
MoveDeviceStateCallback