Get started

Prerequisite
Before starting DriveKit Trip Analysis integration, make sure that you have initialized DriveKit.
Integration
Get framework
DriveKit Trip Analysis SDK is available on CocoaPods master repo.
To access the framework in the repository, add the following lines to your Podfile:
Podfile
1
target 'my-target' do
2
  pod 'DriveKitTripAnalysis'
3
end
Copied!
Then, run pod install
Project configurations
Configure Capabilities
1.Go to the Capabilities tab of your target settings.
2.Turn on Background Modes and enable Location updates.
Configure permissions
As DriveKit requires a user's location and motion data, it is required to get permissions from the user. 
When the application requests permission for background locations or motion activities, a message will be shown to the user. You must configure this message by changing the value for the following keys in Info.plist
NSLocationAlwaysUsageDescription
NSLocationWhenInUseUsageDescription
NSLocationAlwaysAndWhenInUseUsageDescription
NSMotionUsageDescription
Ask for location permission
Since iOS 13 and DriveKit SDK 1.1.3, location permission must be requested in two steps because the "Always Allow" option is no longer available in standard iOS location permission alert. You must first request when in use authorization (locationManager.requestWhenInUseAuthorization()) and then ask the user to choose "Always Allow" option in the app settings and redirect user to the app settings page.
The code below is an example of how to ask user to change location permission for iOS 13 and before, and how to redirect user in the app settings page:
1
let locationManager = CLLocationManager()
2
​
3
func askForLocationPermission() {
4
    if #available(iOS 13.0, *) {
5
        if CLLocationManager.authorizationStatus() == .notDetermined {
6
            locationManager.requestWhenInUseAuthorization()
7
        } else {
8
            self.alertAuthorizations()
9
        }
10
    } else {
11
        if CLLocationManager.authorizationStatus() == .notDetermined {
12
            locationManager.requestAlwaysAuthorization()
13
        } else {
14
            self.alertAuthorizations()
15
        }
16
    }    
17
}
18
​
19
func alertAuthorizations() {
20
    let alert = UIAlertController(title: "Request authorization", message: "In app settings, choose \"Always Allow\" option to automatically detect and record your trips", preferredStyle: .alert)
21
    let settingAction = UIAlertAction(title: "Go to Settings", style: .default, handler: { _ in
22
        guard let settingsUrl = URL(string: UIApplication.openSettingsURLString) else {
23
            return
24
        }   
25
        UIApplication.shared.open(settingsUrl)
26
    })
27
    let cancelAction = UIAlertAction(title: "CANCEL", style: .cancel, handler: nil)
28
    alert.addAction(settingAction)
29
    alert.addAction(cancelAction)
30
     self.present(alert, animated: true)
31
}
Copied!
Motion and Fitness permission
By default, the SDK incorporates the permission request to access Motion and Fitness. This allows for improved transportation mode recognition through the use of activity recognition based on motion properties.
Therefore, if you install DriveKit in your application, a permission request will be displayed to ask for the user's consent.
If you do not want to use this feature and want to control the user experience related to the Motion and Fitness permission request, it can be disabled.
To deactivate the Motion and Fitness permission request, call:
1
DriveKitTripAnalysis.shared.activateActivityRecording(false)
Copied!
Initialization
An initialization phase is required to use the functions offered by the Trip Analysis SDK. In the application's AppDelegate file, import DriveKitTripAnalysis
1
import DriveKitTripAnalysisModule
Copied!
Make the AppDelegate class implement TripListener protocol. This protocol contains 6 methods to implement:
1
func tripPoint(tripPoint: TripPoint) {
2
}
3
func tripStarted(startMode: StartMode) {
4
}
5
func tripCancelled(cancelTrip: CancelTrip) {
6
}
7
func tripFinished(post: PostGeneric, response: PostGenericResponse) {
8
}
9
func tripSavedForRepost(){
10
}
11
func beaconDetected(){
12
}
13
func significantLocationChangeDetected(location: CLLocation){
14
}
15
func sdkStateChanged(state: State){
16
}
Copied!
tripPoint(tripPoint: TripPoint): This method is called when a trip is started and confirmed, for each GPS point recorded by the SDK. Data available in TripPoint object are described here.
tripStarted(startMode: StartMode): This method is called each time a trip is started. StartMode indicates which event starts the trip. Possible values are described here.
tripCancelled(cancelTrip: CancelTrip) : This method is called when a trip is cancelled. CancelTrip indicates which event cancels the trip. Possible values are described here.
tripFinished(post: PostGeneric, response: PostGenericResponse): This method is called when a trip has been recorded by the SDK and sent to DriveQuant's server to be analyzed. PostGeneric object contains raw data sent to DriveQuant's server, PostGenericResponse object contains the trip analysis  made on DriveQuant's server. Detailed description of these data are available here.
tripSavedForRepost(): This method is called if at the end of the trip, the trip can be sent to DriveQuant's server for the analysis. The trip is saved locally on the SDK and will be sent later.
beaconDetected(): This method is called when a beacon sets in the SDK is detected.
significantLocationChangeDetected(): This method is called when a user significant location change is detected. 
sdkStateChanged(state: State): This method is called every time the state of the SDK changed with the new state as parameter. States are described here. 
Then, to initialize Trip Analysis SDK in your app, you must call the initialization method in didFinishLaunchingWithOptions method of your AppDelegate file with launchOptions as parameter.
AppDelegate.swift
1
import DriveKitCoreModule
2
import DriveKitTripAnalysisModule
3
​
4
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
5
    DriveKit.shared.initialize()
6
    DriveKitTripAnalysis.shared.initialize(tripListener: self, appLaunchOptions: launchOptions)
7
    ...    
8
}
Copied!
End of trip notification: Depending on the trip Analysis service's response, we recommend that you specify the notification content if you decide to display a user feedback:
For a vehicle trip, you can display a message such as: Your trip has been analyzed.
For a trip by rail it is better to display the following message: Your journey was made by train.
Check your configuration
You can check if Trip Analysis SDK is well configured with the following method.
Untitled
1
DriveKitTripAnalysis.shared.isConfigured()
Copied!
This method returns true if it is well configured.
Vehicle
To obtain a more precise analysis on driving behaviour, it's recommended to configure the vehicle used by the driver. You can do this by calling the following method:
1
DriveKitTripAnalysis.shared.setVehicle(vehicle: TripVehicle?)
Copied!
A detailed description of vehicle parameter is available here.
If no vehicle is configured a default vehicle will be configured with following parameters:
carTypeIndex = 1
carEngineIndex = 1
carPower = 150
carMass = 1
carGearboxIndex = 2
carConsumption = 4.5
Trip
Start a trip
You can start a trip by calling the following method:
1
DriveKitTripAnalysis.shared.startTrip()
Copied!
If a trip's already started, calling this method will have no effect.
Stop a trip
You can stop a trip by calling the following method. The trip will be stopped instantly:
1
DriveKitTripAnalysis.shared.stopTrip()
Copied!
If a vehicle stops longer than the timeout configured, the trip will be stopped automatically.
If there is no running trip, calling this method will have no effect.
Cancel a trip
If you want to cancel a trip, you can call this method:
1
DriveKitTripAnalysis.shared.cancelTrip()
Copied!
If no trip is running or if the trip has been sent to the server and is currently analyzed, calling this method will have no effect.
SDK recorder state
Two methods are available to determine SDK state.
Untitled
1
DriveKitTripAnalysis.shared.isTripRunning()
Copied!
This method returns false if the SDK is in inactive state, and no trip is currently running.
If you want a more detailed state of the SDK, you can call the following method:
Untitled
1
DriveKitTripAnalysis.shared.getRecorderState()
Copied!
This method returns the state of the SDK:
inactive: No trip is running.
starting: The auto start mode detects a movement of the user and checks if it's a vehicled trip.
running: The trip has been confirmed by the speed of the movement.
stopping: The SDK is in this state when a potential trip end is detected. If the trip continues, the SDK goes back in running state. The duration of the stopping state can be configured.
sending: The trip is finished and is being sent to DriveQuant's server. When the SDK has the response from the server, the state becomes inactive waiting for the next trip.
Repost
Trip Analysis SDK have a repost mechanism, in most cases, when a trip is finished it is sent to DriveQuant's server to be analyzed and once it's done, the result of the analysis is sent back to the SDK. 
In some case, the trip can't be sent to the server (no network for example). In this case, the SDK will save the trip data locally, to send it later. A retry will be attempted when the next trip will start.
If you want to check if there is locally saved trips and if they can be sent to the server, you can call the following method:
1
DriveKitTripAnalysis.shared.checkTripToRepost()
Copied!
Reset
If you need to reset Trip analysis configuration (user logout for example), you can call the following method:
Untitled
1
DriveKitTripAnalysis.shared.reset()
Copied!
All data saved locally by Trip Analysis SDK will be erased and default configuration will be restored.