Initialization

API Interface / Android

Init

The Android MOVE SDK must be initialized by adding MoveSdk.init() at the first line in your Android Application class (onCreate). This instance can then be used to control MOVE SDK services.

After the MOVE SDK has been initialized you also want to add notifications, listeners or activate additional features.

Also you have to configure the MOVE SDK before you are able to call .setup(...).

// your application class

override fun onCreate() {
   // init the MOVE SDK
   val moveSdk = MoveSdk.init(this)   
   
   super.onCreate()

   // Example of adding some notifications, register listener
   // and activate MOVE SDK features.
   moveSdk.apply {
     recognitionNotification(recognitionNotification)
     tripNotification(drivingNotification)
     sdkStateListener(sdkStateListener)
     tripStateListener(tripStateListener)
     authStateUpdateListener(authStateListener)
     initializationListener(initListener)
     setServiceErrorListener(errorListener)
     setServiceWarningListener(warningListener)
     initiateAssistanceCall(assistanceListener)
     deviceDiscoveryListener(deviceDiscoveryListener)
     consoleLogging(true)
   }
   
   // ... continue with Config ...
}

By clicking the links below you can find further information about the usage.

• recognitionNotification
• tripNotification
• sdkStateListener
• tripStateListener
• authStateUpdateListener
• initializationListener

Used Services in the example above and more:

• setServiceErrorListener
• setServiceWarningListener
• initiateAssistanceCall
• consoleLogging
• deviceDiscoveryListener

Config

Whenever you are ready to start the Move SDK, setup() needs to be called with a proper configuration. The following code sample demonstrates a common configuration with driving, walking, cycling, automatic impact detection and assistance call.

   // ... Init ...
   
   // Example of a configuration of the MOVE SDK
   val moveServices: MutableSet<MoveDetectionService> = mutableSetOf()
   
   val drivingServices: MutableSet<DrivingService> = mutableSetOf()
   drivingServices.add(DrivingService.DrivingBehaviour)
   drivingServices.add(DrivingService.DistractionFreeDriving)
   drivingServices.add(DrivingService.DeviceDiscovery)

   val walkingServices: MutableSet<WalkingService> = mutableSetOf()
   walkingServices.add(WalkingService.Location)

   moveServices.add(MoveDetectionService.Driving(drivingServices = drivingServices.toList()))
   moveServices.add(MoveDetectionService.Walking(walkingServices = walkingServices.toList()))
   moveServices.add(MoveDetectionService.Cycling)
   moveServices.add(MoveDetectionService.AutomaticImpactDetection)
   moveServices.add(MoveDetectionService.AssistanceCall)
   
   val moveConfig = MoveConfig(moveDetectionServices = moveServices.toList())
   
   // ... continue with Setup ...

Setup

It is recommended to set up notifications before calling the setup() method.

It is recommended that .setup(...) is called ONLY ONCE!

If .shutdown() was called before then .setup(...) must be redone.

With MoveAuth

Deprecated in the future. The new approach is by using an authCode. see Setup with authCode

The data for the MoveAuth object must be fetched using the given project’s API Key (see MOVE Backend - Example request).

.setup(
    auth: MoveAuth, 
    config: MoveConfig,
    start: Boolean?,
    options: MoveOptions?
)

auth	MoveAuth	The user's Auth object. (see MOVE Backend - Create a new user)
config	MoveConfig	The move configuration
start	Boolean	optional: Default: true -> startAutomaticDetection() is called automatically false -> you have to call startAutomaticDetection() manually
options	MoveOptions	optional: added with v2.3.+

SDK Authentication

Passing the authentication config is required for each setup. The host app is also responsible for monitoring the AuthState changes.

If you want to use startTrip(...) (Manual Start Trip) you have to pass false to the parameter start.

With authCode

The authCode must be fetched using the userId (see MOVE Backend - Example request).

.setup(
    authCode: String, 
    config: MoveConfig,
    start: Boolean?,
    options: MoveOptions?,
    callback: MoveAuthCallback
)

authCode	String	The authCode received from the backend. (see MOVE Backend - Create a new user)
config	MoveConfig	The move configuration
start	Boolean	optional: Default: true -> startAutomaticDetection() is called automatically false -> you have to call startAutomaticDetection() manually
options	MoveOptions
callback	MoveAuthCallback	This listener will report the success or failure during the internal MOVE SDK authentication process. (see MoveAuthResult)

Example of implementing the MoveAuthCallback:

private val moveAuthCallback = object : MoveSdk.MoveAuthCallback {
    override fun onResult(result: MoveAuthResult) {
        when (result.status) {
            AuthSetupStatus.SUCCESS -> {
                // Do something if the result is SUCCESS.
            }
            AuthSetupStatus.INVALID_CODE -> {
                // Do something if the result is INVALID_CODE.
            }
            AuthSetupStatus.NETWORK_ERROR -> {
                // Do something if the result is NETWORK_ERROR.
            }
        }
    }
}

Listeners

Initialization listener

Block that gets invoked on initialization completion with error. On error, MoveConfigurationError is returned. On success, the MoveSdkState will change accordingly.

.initializationListener(listener: MoveInitializeListener)

Parameter		Description
listener	InitializeListener	Block that gets invoked on initialization completion with error. On error, MoveConfigurationError is returned.

Auth state update listener

Provide a block to be invoked every time MoveAuthState changes.

.authStateUpdateListener(callback: AuthStateUpdateListener)

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

Authentication Expiry

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

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

MOVE SDK State listener

Provide a block to be invoked every time MoveSdkState changes.

The host app is expected to be monitoring MoveSdkState changes so it can start the SDK services when MoveSdkState is.readyor handle errors if occurred.

.sdkStateListener(listener: MoveSdkStateListener)

Parameter		Description
listener	MoveSdkStateListener	Block gets called whenever the MoveSdkState changes.

Trip state listener

.tripStateListener(listener: MoveTripStateListener)

Parameter		Description
listener	MoveTripStateListener	A listener where onTripStateChanged gets called whenever the MoveTripState changes

Trip notifications

Passes a notification builder which is used to create a notification reaching places and walking paths. For more information on that please check notification management.

.tripNotification(notification: Notification.Builder)

Parameter	Description
notification	The notification builder to build the notification

Walking notifications

Passes a notification builder which is used to create a notification for places and walking paths. For more information on that please check notification management.

.walkingNotification(notification: Notification.Builder)

Parameter	Description
notification	The notification builder to build the notification

Recognition notifications

Passes a notification builder which is used to create notification while detecting activities, trips and more. For more information on that, please check notification management.

.recognitionNotification(notification: Notification.Builder)

Parameter	Description
notification	The notification builder to build the notification

Trip Metadata

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 MOVE SDK will not use this metadata element in any way, it is just passed through to the project.

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

.metadataProvider(provider: TripMetadataProvider)

Parameter	Description
provider	Callback to provide a bundle of key-value pairs to a trip. The trip is represented with a given start and stop time.

Initialization

Tries to initialize the MOVE SDK. You can only have one initialized MOVE SDK at a time. If you have a MOVE SDK instance already, consider calling shutdownbefore. The initialization process is asynchronous and the host app is expected to register a MoveSDKState listener to monitor successful initialization and start services when MoveSdkState transits toREADY . The host app should also monitor initialization listener to handle potential MoveConfigurationError.

Application Context

Make sure to pass the application context

Parameter	Description
context	Main application context.

fun init(context: Context): MoveSdk

Return
MoveSdk	The instance of the MoveSdk

Throws
MissingAuthenticationException	If the passed configuration is missing, e.g. empty access token

If you have already successfull initialized the MOVE SDK once, try to initialize the MOVE SDK next time in your application in onCreate. This ensures that the MOVE SDK can do its work whenever the application is restarted after termination.